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": "+18015550142",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"external_ref": "your-patient-4821"
}
],
"purpose": "recall_reminder",
"context": "<string>",
"window": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z",
"daily_start": "09:00",
"daily_end": "17:00",
"days": [
3
]
}
}
'import requests
url = "https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests"
payload = {
"contacts": [
{
"phone": "+18015550142",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"external_ref": "your-patient-4821"
}
],
"purpose": "recall_reminder",
"context": "<string>",
"window": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z",
"daily_start": "09:00",
"daily_end": "17:00",
"days": [3]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contacts: [
{
phone: '+18015550142',
first_name: '<string>',
last_name: '<string>',
email: 'jsmith@example.com',
external_ref: 'your-patient-4821'
}
],
purpose: 'recall_reminder',
context: '<string>',
window: {
start: '2023-11-07T05:31:56Z',
end: '2023-11-07T05:31:56Z',
daily_start: '09:00',
daily_end: '17:00',
days: [3]
}
})
};
fetch('https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'contacts' => [
[
'phone' => '+18015550142',
'first_name' => '<string>',
'last_name' => '<string>',
'email' => 'jsmith@example.com',
'external_ref' => 'your-patient-4821'
]
],
'purpose' => 'recall_reminder',
'context' => '<string>',
'window' => [
'start' => '2023-11-07T05:31:56Z',
'end' => '2023-11-07T05:31:56Z',
'daily_start' => '09:00',
'daily_end' => '17:00',
'days' => [
3
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests"
payload := strings.NewReader("{\n \"contacts\": [\n {\n \"phone\": \"+18015550142\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"external_ref\": \"your-patient-4821\"\n }\n ],\n \"purpose\": \"recall_reminder\",\n \"context\": \"<string>\",\n \"window\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\",\n \"daily_start\": \"09:00\",\n \"daily_end\": \"17:00\",\n \"days\": [\n 3\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contacts\": [\n {\n \"phone\": \"+18015550142\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"external_ref\": \"your-patient-4821\"\n }\n ],\n \"purpose\": \"recall_reminder\",\n \"context\": \"<string>\",\n \"window\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\",\n \"daily_start\": \"09:00\",\n \"daily_end\": \"17:00\",\n \"days\": [\n 3\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contacts\": [\n {\n \"phone\": \"+18015550142\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"external_ref\": \"your-patient-4821\"\n }\n ],\n \"purpose\": \"recall_reminder\",\n \"context\": \"<string>\",\n \"window\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\",\n \"daily_start\": \"09:00\",\n \"daily_end\": \"17:00\",\n \"days\": [\n 3\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued",
"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>",
"status": "pending",
"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": "+18015550142",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"external_ref": "your-patient-4821"
}
],
"purpose": "recall_reminder",
"context": "<string>",
"window": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z",
"daily_start": "09:00",
"daily_end": "17:00",
"days": [
3
]
}
}
'import requests
url = "https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests"
payload = {
"contacts": [
{
"phone": "+18015550142",
"first_name": "<string>",
"last_name": "<string>",
"email": "jsmith@example.com",
"external_ref": "your-patient-4821"
}
],
"purpose": "recall_reminder",
"context": "<string>",
"window": {
"start": "2023-11-07T05:31:56Z",
"end": "2023-11-07T05:31:56Z",
"daily_start": "09:00",
"daily_end": "17:00",
"days": [3]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
contacts: [
{
phone: '+18015550142',
first_name: '<string>',
last_name: '<string>',
email: 'jsmith@example.com',
external_ref: 'your-patient-4821'
}
],
purpose: 'recall_reminder',
context: '<string>',
window: {
start: '2023-11-07T05:31:56Z',
end: '2023-11-07T05:31:56Z',
daily_start: '09:00',
daily_end: '17:00',
days: [3]
}
})
};
fetch('https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'contacts' => [
[
'phone' => '+18015550142',
'first_name' => '<string>',
'last_name' => '<string>',
'email' => 'jsmith@example.com',
'external_ref' => 'your-patient-4821'
]
],
'purpose' => 'recall_reminder',
'context' => '<string>',
'window' => [
'start' => '2023-11-07T05:31:56Z',
'end' => '2023-11-07T05:31:56Z',
'daily_start' => '09:00',
'daily_end' => '17:00',
'days' => [
3
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests"
payload := strings.NewReader("{\n \"contacts\": [\n {\n \"phone\": \"+18015550142\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"external_ref\": \"your-patient-4821\"\n }\n ],\n \"purpose\": \"recall_reminder\",\n \"context\": \"<string>\",\n \"window\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\",\n \"daily_start\": \"09:00\",\n \"daily_end\": \"17:00\",\n \"days\": [\n 3\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"contacts\": [\n {\n \"phone\": \"+18015550142\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"external_ref\": \"your-patient-4821\"\n }\n ],\n \"purpose\": \"recall_reminder\",\n \"context\": \"<string>\",\n \"window\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\",\n \"daily_start\": \"09:00\",\n \"daily_end\": \"17:00\",\n \"days\": [\n 3\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://voice.growdental.ai/api/partner/v1/practices/{practiceId}/call-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"contacts\": [\n {\n \"phone\": \"+18015550142\",\n \"first_name\": \"<string>\",\n \"last_name\": \"<string>\",\n \"email\": \"jsmith@example.com\",\n \"external_ref\": \"your-patient-4821\"\n }\n ],\n \"purpose\": \"recall_reminder\",\n \"context\": \"<string>\",\n \"window\": {\n \"start\": \"2023-11-07T05:31:56Z\",\n \"end\": \"2023-11-07T05:31:56Z\",\n \"daily_start\": \"09:00\",\n \"daily_end\": \"17:00\",\n \"days\": [\n 3\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "queued",
"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>",
"status": "pending",
"outcome": "<string>",
"call_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
]
}Authorizations
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
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:
255Path Parameters
Practice ID (must be granted to your app — ungranted IDs return 404).
Body
application/json
Contacts to dial (1–50). Duplicate phone numbers (after E.164
normalization) are rejected with 400 duplicate_contacts.
Required array length:
1 - 50 elementsShow child attributes
Show child attributes
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 - 100Example:
"recall_reminder"
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:
5000Optional 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
Show child attributes
Response
Call request accepted and queued.
A call request with its window, context, and per-contact progress.
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 Aggregate contact-status counts for a call request. Keys beyond the listed ones may appear if new contact statuses are introduced.
Show child attributes
Show child attributes
The free-text context supplied at creation.
Show child attributes
Show child attributes
Show child attributes
Show child attributes