Skip to main content

Add a contact to a Botdog campaign via API

Use Botdog's API to automatically add contacts to campaigns with custom variables and personalization at scale.

R
Written by Robin Choy
Updated over 2 weeks ago

[DISCLAIMER: The integrations are a "Pro" feature and are not available on "Starter" plans]

Adding Contacts to Campaigns via API

Automatically add contacts to your Botdog campaigns using our API with custom personalization variables.

What You Can Build

Here's an example sequence you can create:

  • Visit the person's profile

  • Send LinkedIn invitation with no message

  • If accepted, follow up with: "Hey ##{{firstName}}! ##{{icebreaker}}"

  • If no reply, send: "##{{followupMessage}}"

What You'll Need:

  • Botdog Professional Plan - This is required to get API access

  • Empty Campaign - You can use any existing campaign but we recommend you create one from scratch with the "Import contacts later" option

  • HTTP Client - You can use Postman, cURL, your application, Zapier, Make, etc.

Step 1: Get Your API Key

Important: API access requires a Botdog Professional plan for all accounts in your team. If you only need API access for some accounts, please contact support.

  1. Go to Settings → Integrations → API

  2. Click "Generate a new API Key"

  3. Follow the setup process

  4. Open the Developer Documentation in another tab

Step 2: Create Your Campaign

  1. Go to Create Campaign

  2. Select "Import contacts later (use for API or integrations)"

  3. Choose your sequence structure. Choose the different steps wisely: You will be able to edit messages later, but you you won't be able to add or remove steps once the campaign is started

  4. Use placeholder variables like ##{{icebreaker}} in your messages. They will appear in red until you add contacts, so don't worry at this stage.

  5. Name your campaign and click "Start"

Variables that don't existing yet will be highlighted in red - but don't worry you can still start the campaign and they will map to the correct data once you start importing contacts (and you will be able to double check before steps are actually executed on LinkedIn)

Step 3: Find Your Campaign ID

You need to get your campaign's unique ID using the API:

Endpoint: GET /v1/campaigns

Optional filters:

  • status - You can filter by ACTIVE, PAUSED, ARCHIVED, COMPLETED, or CREATED

  • userIds - You can filter by specific user IDs

Sample Response:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Q4 Sales Outreach",
    "status": "ACTIVE",
    "ownerId": "123e4567-e89b-12d3-a456-426614174000",
    "ownerEmail": "[email protected]",
    "createdAt": "2023-09-15T12:00:00Z",
    "updatedAt": "2023-09-16T14:30:00Z"
  }
]

Copy the campaign id from the response (here 123e4567-e89b-12d3-a456-426614174000). You will need this to add contacts.

Step 4: Add Contacts via API

Use the POST /v1/leads/add_to_campaign endpoint to add contacts with custom variables.

Batch Limit: You can add up to 100 leads per request.

Sample Request Body

{
  "campaignId": "123e4567-e89b-12d3-a456-426614174000",
  "leads": [
    {
      "name": "John Doe",
      "linkedinUrl": "https://www.linkedin.com/in/johndoe",
      "customAttributes": {
        "icebreaker": "I loved your recent post about AI automation!",
        "followupMessage": "Hope you're having a great week!"
      }
    }
  ]
}

Sample Response

{
  "count": 1,
  "campaignId": "123e4567-e89b-12d3-a456-426614174000"
}

Available Fields

  • name (optional) - The contact's full name

  • linkedinUrl (required) - The LinkedIn profile URL

  • title (optional) - Their job title

  • company (optional) - Their company name

  • location (optional) - Their geographic location

  • customAttributes (optional) - Your custom variables for personalization

Important Notes

  • Required field: Only the linkedinUrl field is required

  • Batch processing: You can add up to 100 leads in a single API call

  • Reserved variables: Do not use ##{{firstName}}, ##{{lastName}}, or ##{{currentCompany}} in customAttributes. These are automatically populated in every campaign after visiting the LinkedIn profile

  • Duplicate handling: Contacts already in the same campaign will be automatically skipped based on their LinkedIn URL. You'll see "count":0 in the response when this happens. However, the API won't check for duplicates across different campaigns or existing Botdog contacts, so you're responsible for avoiding double-messaging. To prevent this, use the advanced message settings and select "Choose your condition for sending this message: Send only if it's a new conversation."

Step 5: Verify Everything Works

After you add contacts via the API, you should verify that everything is working correctly:

  1. Check your campaign: Go to the campaigns dashboard

  2. Edit messages: Hover over your campaign name and click "View and edit sequence"

  3. Use custom variables: Your custom variables will now appear in the dropdown menu

  4. Preview messages: Click "Show preview" to see how your messages look with real data

  5. View contact data: Click the contacts number, then select a person to see their custom attributes

Click on View and Edit Sequence to make sure the messaging is right

A scheduler will now run and schedule the next actions, which might take a few hours to execute - so don't worry if actions are not immediately executed, they soon will be!

Easier Setup with Zapier

If you prefer a visual workflow builder over direct API calls, our Zapier integration makes this entire process much simpler. You can connect Botdog to hundreds of other apps without writing any code.

Ideas for Use Cases

  • Add LinkedIn automation capabilities directly to your own application or AI agent (reach out to us if that's your use case - we already support several AI Agents)

  • Sync contacts from your CRM (HubSpot, Attio, Salesforce) or traffic enrichment tool (RB2B) to automatically start outreach

  • Trigger campaigns based on website behavior (sign ups, demo requests, whitepaper downloads, etc.)

  • Add leads from webinar attendees or event registrations to follow-up campaigns

  • Connect your lead generation forms directly to LinkedIn outreach sequences

How to Make This Better

  • You can use our AI Lead Review feature to filter contacts with natural language ("only proceed if the contact is a CEO based in the US") to make sure your automation is reaching the right people

  • Enrich contact data with services like FullEnrich before adding to campaigns for better response rates

  • Set up webhooks to get notified when people reply and automatically update your CRM

  • Connect multiple campaigns together - move accepted connections to follow-up sequences automatically

Need Help?

Please contact our support team if you need assistance setting up API access or if you have questions about implementation.

Did this answer your question?