Campaign API Trigger (Admins Only)

The Campaign API Trigger allows you to programmatically add contacts to campaigns and start automated calls through a REST API. This is ideal for integrating with your existing systems, workflows, or custom applications.

Overview

The API Trigger provides a simple REST endpoint that accepts contact information and automatically:

• Creates or updates the contact in your system
• Adds the contact to the specified campaign
• Optionally customizes the call with template overwrites
• Schedules the automated call according to campaign settings

---

API Endpoint

Method: POST

URL: https://api.plugandplai.ai/campaign/{campaign-id}/trigger-contact

Authentication: Bearer token (your service API key)

---

Request Format

Headers

Content-Type: application/json
Authorization: Bearer YOUR_SERVICE_API_KEY

Request Body

The request body must be a JSON object with the following structure:

{
  "email": "contact@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+49 123 456789",
  "tags": ["tag1", "tag2"],
  "metadata": {
    "customField1": "value1",
    "customField2": "value2"
  },
  "templateOverwrite": {
    "goal": "Custom goal for this specific contact",
    "company": "Specific company name",
    "product": "Specific product information"
  }
}

Field Descriptions

Required Fields

• phone (string): Contact's phone number in international format (e.g., "+49 123 456789")

Optional Fields

• email (string): Contact's email address
• firstName (string): Contact's first name
• lastName (string): Contact's last name
• tags (array of strings): Tags to assign to the contact for organization and filtering
• metadata (object): Custom key-value pairs for additional contact information
• templateOverwrite (object): Custom values to override assistant template variables for this contact

---

Template Overwrites

Template overwrites allow you to customize the assistant's prompt variables for each contact individually. This makes your calls more personalized and relevant.

What Are Template Overwrites?

When you configure your assistant, you can define template variables (also called "additional variables") that appear in the assistant's prompt. These variables might include:

• Company name
• Product information
• Campaign goals
• Special offers
• Appointment details

By default, these variables use the values set in your assistant configuration. With template overwrites, you can provide different values for specific contacts when triggering the campaign via API.

How to Use Template Overwrites

In the templateOverwrite object, include the variable names as keys and your custom values as strings:

{
  "templateOverwrite": {
    "goal": "Qualify the lead for premium product offering",
    "company": "Acme Corporation",
    "product": "Enterprise Software Package"
  }
}

Which Variables Can Be Overwritten?

The available template variables depend on your assistant's schema configuration. Common examples include:

• goal: The specific goal for this call
• company: Company name to mention during the call
• product: Product or service to discuss
• Custom variables defined in your assistant's schema

To see which variables are available for your campaign, check the API documentation example in the campaign's "API Trigger" tab.

---

Getting Your API Key

1. Navigate to your Account Settings
2. Find the Service API Key section
3. Copy your API key
4. Keep this key secure - it provides access to your account

---

Using the API

Example with cURL

curl -X POST https://api.plugandplai.ai/campaign/abc123/trigger-contact \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SERVICE_API_KEY" \
  -d '{
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "+49 123 456789",
    "tags": ["qualified-lead", "enterprise"],
    "metadata": {
      "source": "website-form",
      "interest": "premium-plan"
    },
    "templateOverwrite": {
      "goal": "Schedule a product demo",
      "company": "Acme Corp"
    }
  }'

Example with JavaScript

const response = await fetch('https://api.plugandplai.ai/campaign/abc123/trigger-contact', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SERVICE_API_KEY'
  },
  body: JSON.stringify({
    email: 'john.doe@example.com',
    firstName: 'John',
    lastName: 'Doe',
    phone: '+49 123 456789',
    tags: ['qualified-lead', 'enterprise'],
    metadata: {
      source: 'website-form',
      interest: 'premium-plan'
    },
    templateOverwrite: {
      goal: 'Schedule a product demo',
      company: 'Acme Corp'
    }
  })
});

const result = await response.json();

Example with Python

import requests

url = 'https://api.plugandplai.ai/campaign/abc123/trigger-contact'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SERVICE_API_KEY'
}
data = {
    'email': 'john.doe@example.com',
    'firstName': 'John',
    'lastName': 'Doe',
    'phone': '+49 123 456789',
    'tags': ['qualified-lead', 'enterprise'],
    'metadata': {
        'source': 'website-form',
        'interest': 'premium-plan'
    },
    'templateOverwrite': {
        'goal': 'Schedule a product demo',
        'company': 'Acme Corp'
    }
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

---

Response Format

Success Response

Status Code: 200 OK

[
  {
    "id": "campaign-call-id",
    "campaignId": "abc123",
    "contactId": "contact-id",
    "status": "pending",
    "retries": 0,
    "createdAt": "2026-01-22T10:30:00Z"
  }
]

Error Responses

Status Code: 400 Bad Request

• Missing required fields
• Invalid phone number format
• Invalid request body

Status Code: 401 Unauthorized

• Missing or invalid API key

Status Code: 404 Not Found

• Campaign not found

---

Best Practices

Security

• Keep your API key secure: Never share it publicly or commit it to version control
• Use HTTPS: Always use the secure HTTPS endpoint
• Rotate keys regularly: Update your API keys periodically for security

Phone Numbers

• Use international format: Include country code (e.g., "+49 123 456789")
• Validate before sending: Ensure phone numbers are valid and properly formatted
• Avoid duplicates: The system prevents duplicate contacts based on phone numbers

Template Overwrites

• Be specific: Provide clear, relevant information in template overwrites
• Test first: Try with a few contacts before bulk operations
• Match your schema: Only use variable names defined in your assistant's schema
• Keep values concise: Template values should be clear and not too long

Integration Tips

• Handle errors gracefully: Implement proper error handling in your integration
• Monitor results: Check campaign results regularly to ensure contacts are being added correctly
• Rate limiting: Be mindful of API rate limits when sending bulk requests
• Metadata usage: Use the metadata field to track where contacts came from for better analytics

---

Use Cases

CRM Integration

Automatically trigger campaigns when:

• A lead reaches a certain score
• A deal enters a specific stage
• A contact shows interest in a product

Website Forms

Add contacts to campaigns from:

• Contact forms
• Newsletter signups
• Demo request forms
• Lead magnets

Marketing Automation

Integrate with tools like:

• Email marketing platforms
• Landing page builders
• Webinar platforms
• E-commerce systems

Custom Applications

Build your own workflows:

• After-hours inquiry follow-up
• Abandoned cart recovery
• Event registration follow-up
• Customer satisfaction surveys

---

Troubleshooting

Contact Not Added

• Verify the campaign ID is correct
• Check that the phone number is in valid international format
• Ensure your API key has proper permissions
• Confirm the campaign is not paused or ended

Template Overwrites Not Working

• Verify the variable names match your assistant's schema
• Check that template values are strings, not objects or arrays
• Ensure your assistant has template parts configured

Authentication Errors

• Verify your API key is correct and hasn't expired
• Check that the Authorization header is properly formatted
• Ensure you're using "Bearer" prefix before the API key

---

Getting Help

If you encounter issues with the API Trigger:

1. Check the API documentation in your campaign's "API Trigger" tab
2. Verify your request format matches the examples
3. Review error messages for specific issues
4. Contact support for technical assistance

---

For more information about campaigns, see the Campaigns Overview.