External API

Build on WingsGotYou

Trigger AI phone calls programmatically from any service — N8n, Zapier, your CRM, a custom backend, or a simple cURL command.

Base URL https://api.wingsgotyou.com

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:

bash
curl -X POST https://api.wingsgotyou.com/api-keys/ \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Integration"}'
Save the key immediately — the full API key is shown only once and cannot be retrieved later. You'll see a prefix like wgy_abcd in the dashboard for identification.

2. Make a Call

bash
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

bash
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.

bash
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:

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

FieldTypeDescription
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

bash
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

json
{
  "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

StatusDescription
401Invalid or missing API key
402No minutes remaining on your account
422Invalid 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

json
{
  "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

json
{
  "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

StatusDescription
in_progressWing is on the call
needs_userWing needs the account holder to join (rare — only when human verification is required)
completedCall finished successfully
failedCall could not connect (busy, no answer, etc.)

Goal Rating

RatingMeaning
3Goal fully achieved
2Goal partially achieved
1Goal 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.

Plan requirement: Call scheduling requires a plan that includes this feature. If your plan doesn't support scheduling, the API returns 403.
POST /api/v1/call/schedule

Request Body

FieldTypeRequiredDescription
tostringYesPhone number (US/CA, any format)
company_namestringYesCompany name (auto-created if new)
goalstringYesWhat Wing should accomplish
scheduled_atstringYesISO 8601 datetime (e.g. "2026-04-01T14:30:00-04:00")
timezonestringNoIANA timezone for display (default "UTC")
callback_urlstringNoURL to POST results when the executed call completes
notification_preferencestringNoPost-call notification: "email", "sms", "both", or omit for profile default

Example

bash
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

json
{
  "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

StatusDescription
401Invalid or missing API key
403Your plan does not include call scheduling
422Invalid phone number, time not at least 5 minutes in the future, or invalid notification_preference

Managing Scheduled Calls

GET /api/v1/call/schedule

List your pending and executing scheduled calls.

GET /api/v1/call/schedule/{id}/status

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.

PATCH /api/v1/call/schedule/{id}

Edit a pending scheduled call (goal, time, timezone). Returns 409 if the call is no longer pending.

DELETE /api/v1/call/schedule/{id}

Cancel a pending or failed scheduled call.

Status Values

StatusDescription
pendingWaiting for the scheduled time
executingBeing initiated right now
completedCall was placed — use call_poll_url to track it
failedCould not execute (insufficient balance, company deleted, etc.)
cancelledCancelled 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

headers
Content-Type: application/json
User-Agent: CallBridge-Webhook/1.0
X-CallBridge-Event: call.completed

Payload

json
{
  "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"
}
Your endpoint should return a 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.

bash
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"
  }'
When a 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

  1. Create an API key in WingsGotYou
  2. In N8n, add a Webhook node as the trigger (this gives you a callback URL)
  3. Add an HTTP Request node pointing to POST /api/v1/call with your API key and a JSON body mapping your workflow fields to to, company_name, goal, and callback_url
  4. The Webhook node receives the call results when Wing finishes
  5. Add downstream nodes to update your CRM, send an email, post to Slack, etc.
json — N8n HTTP Request body
{
  "to": "{{ $json.phone_number }}",
  "company_name": "{{ $json.company }}",
  "goal": "{{ $json.goal }}",
  "callback_url": "{{ $node.Webhook.url }}"
}

Zapier

  1. Create a Zap with trigger: Webhooks by Zapier > Catch Hook
  2. Copy the Zapier webhook URL
  3. Register it as a persistent webhook in WingsGotYou (see Registered Webhooks above)
  4. Every completed call will trigger your Zap with the full result payload
bash — Register Zapier webhook
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

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

bash
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.

bash
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

ConstraintLimit
Call minutesConsumed from your account balance
API key authRate-limited to prevent abuse
File uploads10 MB per file
Document storageSubject to your plan's quota

Errors

All errors return JSON with a detail field:

json
{"detail": "No minutes remaining."}
StatusMeaning
401Invalid or missing authentication
402No minutes remaining on account
403Feature not available on your plan (e.g. call scheduling)
404Call or resource not found
409Resource in wrong state for this action (e.g. editing a non-pending scheduled call)
413File too large or storage quota exceeded
422Invalid 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.