Quickstart

This walkthrough uses an existing agent and phone number from your workspace. You need an API key with agents.view, phone_numbers.view, campaigns.edit and calls.view (see Authentication).

Starting a campaign places real, billed calls. Use your own test numbers while you experiment.

Set your key once:

export PINEYARD_API_KEY="pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Find an agent and a phone number

curl https://api.pineyard.ai/agents \
  -H "Authorization: Bearer $PINEYARD_API_KEY"

curl https://api.pineyard.ai/phone-numbers \
  -H "Authorization: Bearer $PINEYARD_API_KEY"

const API = 'https://api.pineyard.ai'
const headers = {
  Authorization: `Bearer ${process.env.PINEYARD_API_KEY}`,
  'Content-Type': 'application/json',
}

const agents = await (await fetch(`${API}/agents`, { headers })).json()
const { items: numbers } = await (await fetch(`${API}/phone-numbers`, { headers })).json()
const agentId = agents[0].id
const phoneNumberId = numbers[0].id

import os, requests

API = "https://api.pineyard.ai"
headers = {"Authorization": f"Bearer {os.environ['PINEYARD_API_KEY']}"}

agents = requests.get(f"{API}/agents", headers=headers).json()
numbers = requests.get(f"{API}/phone-numbers", headers=headers).json()["items"]
agent_id = agents[0]["id"]
phone_number_id = numbers[0]["id"]

Note the agent’s variables: these are the per-contact fields its script uses (for example first_name). Agent responses never include the prompt text.

Create a campaign

New campaigns start as drafts.

curl -X POST https://api.pineyard.ai/campaigns \
  -H "Authorization: Bearer $PINEYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "October outreach",
    "agentId": "00000000-0000-4000-8000-000000000001",
    "timezone": "America/New_York",
    "dailyWindowStart": "10:00",
    "dailyWindowEnd": "18:00"
  }'

const created = await (await fetch(`${API}/campaigns`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'October outreach',
    agentId,
    timezone: 'America/New_York',
    dailyWindowStart: '10:00',
    dailyWindowEnd: '18:00',
  }),
})).json()
const campaignId = created.campaignId

created = requests.post(f"{API}/campaigns", headers=headers, json={
    "name": "October outreach",
    "agentId": agent_id,
    "timezone": "America/New_York",
    "dailyWindowStart": "10:00",
    "dailyWindowEnd": "18:00",
}).json()
campaign_id = created["campaignId"]

Response (201)

{ "campaignId": "00000000-0000-4000-8000-0000000000c1", "contactsAdded": 0, "contactsSkipped": 0, "skippedReasons": [] }

Attach a phone number

Calls are placed from the numbers attached to the campaign.

curl -X POST https://api.pineyard.ai/campaigns/00000000-0000-4000-8000-0000000000c1/phone-numbers \
  -H "Authorization: Bearer $PINEYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumberIds": ["00000000-0000-4000-8000-000000000002"]}'

await fetch(`${API}/campaigns/${campaignId}/phone-numbers`, {
  method: 'POST', headers, body: JSON.stringify({ phoneNumberIds: [phoneNumberId] }),
}) // 204 No Content

requests.post(f"{API}/campaigns/{campaign_id}/phone-numbers", headers=headers,
              json={"phoneNumberIds": [phone_number_id]})  # 204 No Content

Add contacts

Phone numbers must be in E.164 format. Put the agent’s variables in metadata. Up to 10,000 contacts per request.

curl -X POST https://api.pineyard.ai/campaigns/00000000-0000-4000-8000-0000000000c1/contacts \
  -H "Authorization: Bearer $PINEYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone": "+15555550100", "name": "Jordan Example", "metadata": { "first_name": "Jordan" } },
      { "phone": "+15555550101", "name": "Sam Example", "metadata": { "first_name": "Sam" } }
    ]
  }'

const added = await (await fetch(`${API}/campaigns/${campaignId}/contacts`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    contacts: [
      { phone: '+15555550100', name: 'Jordan Example', metadata: { first_name: 'Jordan' } },
      { phone: '+15555550101', name: 'Sam Example', metadata: { first_name: 'Sam' } },
    ],
  }),
})).json()

added = requests.post(f"{API}/campaigns/{campaign_id}/contacts", headers=headers, json={
    "contacts": [
        {"phone": "+15555550100", "name": "Jordan Example", "metadata": {"first_name": "Jordan"}},
        {"phone": "+15555550101", "name": "Sam Example", "metadata": {"first_name": "Sam"}},
    ]
}).json()

Response (201)

{ "added": 2, "total": 2 }

Start the campaign

curl -X POST https://api.pineyard.ai/campaigns/00000000-0000-4000-8000-0000000000c1/start \
  -H "Authorization: Bearer $PINEYARD_API_KEY"

const res = await fetch(`${API}/campaigns/${campaignId}/start`, { method: 'POST', headers })
if (res.status !== 204) console.error(await res.json()) // e.g. { error: 'insufficient_credits' }

res = requests.post(f"{API}/campaigns/{campaign_id}/start", headers=headers)
if res.status_code != 204:
    print(res.json())  # e.g. {"error": "insufficient_credits"}

A 204 means the campaign is running. Calls go out within the calling window you set.

Read the results

Check progress, then list the campaign’s calls:

curl https://api.pineyard.ai/campaigns/00000000-0000-4000-8000-0000000000c1/stats \
  -H "Authorization: Bearer $PINEYARD_API_KEY"

curl "https://api.pineyard.ai/calls?campaignId=00000000-0000-4000-8000-0000000000c1&limit=50" \
  -H "Authorization: Bearer $PINEYARD_API_KEY"

const stats = await (await fetch(`${API}/campaigns/${campaignId}/stats`, { headers })).json()
const calls = await (await fetch(`${API}/calls?campaignId=${campaignId}&limit=50`, { headers })).json()

stats = requests.get(f"{API}/campaigns/{campaign_id}/stats", headers=headers).json()
calls = requests.get(f"{API}/calls", headers=headers,
                     params={"campaignId": campaign_id, "limit": 50}).json()

Stats response

{ "status": "RUNNING", "total": 2, "PENDING": 1, "IN_FLIGHT": 0, "MESSAGED": 0, "COMPLETED": 1, "FAILED": 0, "SKIPPED": 0 }

Fetch one call with GET /calls/{id} for its transcript, summary and extracted data.

Next steps

Run a campaign end to end

Scheduling, retries, pausing and the /v1 lead API.

Receive results

Get each lead’s result pushed to your server.

Recordings & transcripts

Download audio and read transcripts.

Get started

Concepts

Guides

Next steps

Run a campaign end to end

Receive results

Recordings & transcripts

​Next steps

Run a campaign end to end

Receive results

Recordings & transcripts

Next steps