Build on WingsGotYou
Trigger AI phone calls programmatically from any service — N8n, Zapier, your CRM, a custom backend, or a simple cURL command.
Quick Start
Get from zero to your first API-triggered call in three steps.
1. Get an API Key
Log in to WingsGotYou and create an API key from the web app, or use the API:
curl -X POST https://api.wingsgotyou.com/api-keys/ \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "My Integration"}'
wgy_abcd in the dashboard for identification.
2. Make a Call
curl -X POST https://api.wingsgotyou.com/api/v1/call \
-H "X-API-Key: wgy_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"to": "+18005551234",
"company_name": "Comcast",
"goal": "Cancel my subscription and get a refund for the last month"
}'
Wing immediately dials the number and handles the call autonomously.
3. Get the Results
Option A: Poll for status
curl https://api.wingsgotyou.com/api/v1/call/CA.../status \
-H "X-API-Key: wgy_your_key_here"
Option B: Receive results via callback (RECOMMENDED)
Pass a callback_url when triggering the call. Wing POSTs the results to your URL when the call completes — no polling needed.
curl -X POST https://api.wingsgotyou.com/api/v1/call \
-H "X-API-Key: wgy_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"to": "+18005551234",
"company_name": "Comcast",
"goal": "Cancel my subscription",
"callback_url": "https://your-server.com/webhook/wing-result"
}'
Authentication
All External API endpoints require an API key sent via the X-API-Key header:
X-API-Key: wgy_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
API keys are scoped to your user account. All calls made via a key are billed against your account's minutes balance.
Endpoints
POST /api/v1/call
Trigger an outbound call. Wing dials the number, navigates IVR menus, speaks to customer service, and works toward your goal.
Request Body
| Field | Type | Description | |
|---|---|---|---|
to |
string | Required | Phone number to call. US/CA numbers in any format: +18005551234, (800) 555-1234, 800-555-1234 |
company_name |
string | Required | Company name. If this phone number isn't already in your Phone Book, a new entry is created automatically and saved to your Phone Book |
goal |
string | Required | What Wing should accomplish. Be specific — include amounts, reference numbers, and desired outcomes |
callback_url |
string | Optional | URL to receive results when the call completes. Wing POSTs a JSON payload to this URL |
use_own_caller_id |
bool | Optional | Use your verified caller ID so the company sees your number. Requires Identity Pack. Defaults to false |
voice_id |
string | Optional | TTS voice for Wing. Polly.* for AWS Polly, Cartesia UUID, or "__me__" for your cloned voice |
notification_preference |
string | Optional | Post-call notification: "email", "sms", "both", or omit for profile default |
Example Request
curl -X POST https://api.wingsgotyou.com/api/v1/call \
-H "X-API-Key: wgy_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"to": "+18005551234",
"company_name": "Comcast",
"goal": "Dispute the $45 late fee on my account. Account number is 12345678.",
"callback_url": "https://hooks.example.com/wing-result"
}'
Response 200
{
"call_sid": "CA31cab93ea83cd1a0a8514095e7e1ce0d",
"status": "queued",
"to": "+1 800-555-1234",
"company_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"goal": "Dispute the $45 late fee on my account...",
"poll_url": "/api/v1/call/CA31cab93ea83cd1a0a8514095e7e1ce0d/status"
}
Error Responses
| Status | Description |
|---|---|
| 401 | Invalid or missing API key |
| 402 | No minutes remaining on your account |
| 422 | Invalid phone number (must be US or Canada), or invalid notification_preference |
GET /api/v1/call/{call_sid}/status
Poll the status and results of a call. Use the call_sid returned from POST /api/v1/call.
Response — Call in progress
{
"call_sid": "CA31cab93ea83cd1a0a8514095e7e1ce0d",
"status": "in_progress",
"company_name": "Comcast",
"goal": "Dispute the $45 late fee on my account",
"goal_summary": "Dispute late fee",
"outcome": null,
"summary": null,
"goal_rating": null,
"transcript": [],
"duration_seconds": null,
"created_at": "2026-03-29T18:00:00+00:00",
"answered_at": "2026-03-29T18:00:12+00:00",
"ended_at": null
}
Response — Call completed
{
"call_sid": "CA31cab93ea83cd1a0a8514095e7e1ce0d",
"status": "completed",
"company_name": "Comcast",
"goal": "Dispute the $45 late fee on my account",
"goal_summary": "Dispute late fee",
"outcome": "Late fee of $45 waived",
"summary": "Wing called Comcast and navigated to billing...",
"goal_rating": 3,
"transcript": [
["agent", "Hi, I'm calling on behalf of Mark..."],
["them", "Sure, I can look into that..."]
],
"duration_seconds": 247,
"created_at": "2026-03-29T18:00:00+00:00",
"answered_at": "2026-03-29T18:00:12+00:00",
"ended_at": "2026-03-29T18:04:07+00:00"
}
Status Values
| Status | Description |
|---|---|
in_progress | Wing is on the call |
needs_user | Wing needs the account holder to join (rare — only when human verification is required) |
completed | Call finished successfully |
failed | Call could not connect (busy, no answer, etc.) |
Goal Rating
| Rating | Meaning |
|---|---|
3 | Goal fully achieved |
2 | Goal partially achieved |
1 | Goal not achieved (but time was still saved navigating the IVR) |
Schedule a Call
Schedule a call for a future date and time. Wing executes the call automatically — you don't need to be online or logged in.
403.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
to | string | Yes | Phone number (US/CA, any format) |
company_name | string | Yes | Company name (auto-created if new) |
goal | string | Yes | What Wing should accomplish |
scheduled_at | string | Yes | ISO 8601 datetime (e.g. "2026-04-01T14:30:00-04:00") |
timezone | string | No | IANA timezone for display (default "UTC") |
callback_url | string | No | URL to POST results when the executed call completes |
notification_preference | string | No | Post-call notification: "email", "sms", "both", or omit for profile default |
Example
curl -X POST https://api.wingsgotyou.com/api/v1/call/schedule \
-H "X-API-Key: wgy_your_key" \
-H "Content-Type: application/json" \
-d '{
"to": "+18005551234",
"company_name": "Comcast",
"goal": "Cancel my internet subscription",
"scheduled_at": "2026-04-01T14:30:00-04:00",
"timezone": "America/New_York"
}'
Response 200
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "pending",
"to": "+1 800-555-1234",
"company_id": "uuid",
"goal": "Cancel my internet subscription",
"scheduled_at": "2026-04-01T18:30:00+00:00",
"poll_url": "/api/v1/call/schedule/3fa85f64-.../status"
}
Errors
| Status | Description |
|---|---|
401 | Invalid or missing API key |
403 | Your plan does not include call scheduling |
422 | Invalid phone number, time not at least 5 minutes in the future, or invalid notification_preference |
Managing Scheduled Calls
List your pending and executing scheduled calls.
Poll a scheduled call's status. Once executed, includes call_sid and call_poll_url to track the actual call result. Response includes goal_summary, failure_reason, and call_sid/call_poll_url when applicable.
Edit a pending scheduled call (goal, time, timezone). Returns 409 if the call is no longer pending.
Cancel a pending or failed scheduled call.
Status Values
| Status | Description |
|---|---|
pending | Waiting for the scheduled time |
executing | Being initiated right now |
completed | Call was placed — use call_poll_url to track it |
failed | Could not execute (insufficient balance, company deleted, etc.) |
cancelled | Cancelled before execution |
Callback Webhook
When you provide a callback_url in your call request, Wing POSTs a JSON payload to that URL when the call completes. This is the recommended pattern for automation — no polling needed.
Headers
Content-Type: application/json
User-Agent: CallBridge-Webhook/1.0
X-CallBridge-Event: call.completed
Payload
{
"event": "call.completed",
"call_sid": "CA31cab93ea83cd1a0a8514095e7e1ce0d",
"company_name": "Comcast",
"company_phone": "+18005551234",
"goal": "Dispute the $45 late fee on my account",
"goal_summary": "Dispute late fee",
"outcome": "Late fee of $45 waived",
"summary": "Wing called Comcast and navigated to billing...",
"goal_rating": 3,
"status": "completed",
"transcript": [
["agent", "Hi, I'm calling on behalf of Mark..."],
["them", "Sure, I can look into that..."]
],
"time_saved_seconds": 240,
"created_at": "2026-03-29T18:00:00+00:00",
"answered_at": "2026-03-29T18:00:12+00:00",
"ended_at": "2026-03-29T18:04:07+00:00"
}
2xx status code. Delivery failures are logged but do not affect the call result.
Registered Webhooks
For recurring integrations, register a persistent webhook URL that fires for every completed call on your account — not just API-triggered ones.
POST /webhooks/
Create a new webhook.
curl -X POST https://api.wingsgotyou.com/webhooks/ \
-H "X-API-Key: wgy_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"name": "Send results to Slack",
"url": "https://hooks.slack.com/services/T00/B00/xxxx",
"secret": "my-signing-secret"
}'
secret is set, the X-CallBridge-Signature header contains the HMAC-SHA256 hex digest of the raw JSON body, signed with your secret. Verify it server-side to confirm the payload came from WingsGotYou.
GET /webhooks/
List all registered webhooks.
PATCH /webhooks/{id}
Update a webhook's name, URL, secret, events, or active status.
DELETE /webhooks/{id}
Delete a webhook.
POST /webhooks/{id}/test
Send a test payload to verify your webhook endpoint is working.
Integrations
Wing works with any service that can make HTTP requests. Here are step-by-step guides for the most popular platforms.
N8n
- Create an API key in WingsGotYou
- In N8n, add a Webhook node as the trigger (this gives you a callback URL)
- Add an HTTP Request node pointing to
POST /api/v1/callwith your API key and a JSON body mapping your workflow fields toto,company_name,goal, andcallback_url - The Webhook node receives the call results when Wing finishes
- Add downstream nodes to update your CRM, send an email, post to Slack, etc.
{
"to": "{{ $json.phone_number }}",
"company_name": "{{ $json.company }}",
"goal": "{{ $json.goal }}",
"callback_url": "{{ $node.Webhook.url }}"
}
Zapier
- Create a Zap with trigger: Webhooks by Zapier > Catch Hook
- Copy the Zapier webhook URL
- Register it as a persistent webhook in WingsGotYou (see Registered Webhooks above)
- Every completed call will trigger your Zap with the full result payload
curl -X POST https://api.wingsgotyou.com/webhooks/ \
-H "X-API-Key: wgy_your_key_here" \
-H "Content-Type: application/json" \
-d '{"name": "Zapier", "url": "https://hooks.zapier.com/hooks/catch/xxx/yyy/"}'
Python
import requests
import time
API_KEY = "wgy_your_key_here"
BASE = "https://api.wingsgotyou.com"
HEADERS = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
# Trigger the call
resp = requests.post(f"{BASE}/api/v1/call", headers=HEADERS, json={
"to": "+18005551234",
"company_name": "Comcast",
"goal": "Cancel my internet subscription",
})
call_sid = resp.json()["call_sid"]
print(f"Call started: {call_sid}")
# Poll until complete
while True:
status = requests.get(
f"{BASE}/api/v1/call/{call_sid}/status",
headers=HEADERS
).json()
print(f"Status: {status['status']}")
if status["status"] in ("completed", "failed"):
break
time.sleep(10)
# Print results
print(f"Outcome: {status['outcome']}")
print(f"Rating: {status['goal_rating']}/3")
print(f"Summary: {status['summary']}")
cURL One-liner
curl -s -X POST https://api.wingsgotyou.com/api/v1/call \
-H "X-API-Key: wgy_your_key" \
-H "Content-Type: application/json" \
-d '{"to":"+18005551234","company_name":"Comcast","goal":"Cancel subscription"}' \
| jq .call_sid
API Key Management
POST /api-keys/
Create a new API key. The full key is returned once — store it securely.
curl -X POST https://api.wingsgotyou.com/api-keys/ \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "N8n Production"}'
GET /api-keys/
List all API keys (prefix and metadata only — full keys are never returned).
DELETE /api-keys/{id}
Revoke an API key. Takes effect immediately.
Rate Limits
| Constraint | Limit |
|---|---|
| Call minutes | Consumed from your account balance |
| API key auth | Rate-limited to prevent abuse |
| File uploads | 10 MB per file |
| Document storage | Subject to your plan's quota |
Errors
All errors return JSON with a detail field:
{"detail": "No minutes remaining."}
| Status | Meaning |
|---|---|
| 401 | Invalid or missing authentication |
| 402 | No minutes remaining on account |
| 403 | Feature not available on your plan (e.g. call scheduling) |
| 404 | Call or resource not found |
| 409 | Resource in wrong state for this action (e.g. editing a non-pending scheduled call) |
| 413 | File too large or storage quota exceeded |
| 422 | Invalid input (bad phone number, missing fields) |
Tips for Better Results
- Be specific in your goal. "Cancel my subscription" works, but "Cancel my internet subscription, reference number #12345, and request a refund for the current billing cycle" works much better.
- Include reference numbers. Account numbers, order IDs, and confirmation codes help Wing navigate faster.
- Use the company's customer service number. Wing navigates IVR menus, so the main support line works best.
- Add account info to the Phone Book. If you call the same company often, add their account number and other details via the web app — Wing will use them automatically on every call.