Campaigns

Campaigns

Campaign management endpoints for retrieving campaign information and managing campaign-related operations.

All endpoints require Authorization with Bearer JWT token.

Available Endpoints

List All Accounts and Top-Level Campaigns

• Endpoint: GET /api/v1/campaigns
• Description: Retrieves all campaigns linked to a reseller, the payload will also return the account id for each campaign
• Purpose: Use this data to get all campaigns associated with each account
• Headers: Authorization: Bearer <TOKEN>

Get Campaign Notes

• Endpoint: GET /api/v2/campaigns/notes
• Description: Retrieve campaign notes for a specific campaign
• Parameters:
  • campaign_id (integer): The ID of the campaign (required query parameter)
• Headers: Authorization: Bearer <TOKEN>

Update Campaign Notes

• Endpoint: PUT /api/v2/campaigns/notes
• Description: Update campaign notes for a specific campaign
• Required Fields:
  • campaign_id (integer): The ID of the campaign
  • writer_instructions (string): Instructions for the writer
  • additional_instructions (string): Additional instructions for the writer
• Headers: Authorization: Bearer <TOKEN>

Example Requests

List All Accounts and Top-Level Campaigns

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v1/campaigns"

Get Campaign Notes

curl -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     "https://uat.services.semify.com/api/v2/campaigns/notes?campaign_id=12345"

Update Campaign Notes

curl -X PUT \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "campaign_id": 12345,
       "writer_instructions": "Focus on local SEO and content marketing",
       "additional_instructions": "Include industry-specific keywords and maintain a professional tone"
     }' \
     "https://uat.services.semify.com/api/v2/campaigns/notes"

Sample Response

{
  "data": [
    {
      "campaign_start_date": "2024-07-06T19:09:14Z",
      "ppc_monthly_budget_invoice_status": 0,
      "campaign_id": 1234567,
      "account_id": 9654321,
      "campaign_stage_id": 5,
      "campaign_end_date": "2029-07-06T19:09:14Z",
      "ppc_monthly_budget": 0,
      "discount": 0,
      "decline_gmb": 0,
      "campaign_name": "semify.com",
      "decline_reviews": 0,
      "campaign_stage_name": "Closed/Won",
      "decline_blog": 0,
      "status": 1
    }
  ],
  "messages": ["Campaigns successfully retrieved."],
  "error": false,
  "pagination": {
    "totalPages": 1,
    "maxRows": 0,
    "offset": 0,
    "page": 1,
    "totalRecords": 1
  }
}

Campaign Notes Responses

Get Campaign Notes Response

{
  "error": false,
  "messages": [
    "Campaign notes retrieved successfully"
  ],
  "pagination": {},
  "data": {
    "campaign_id": 12345,
    "writer_instructions": "Focus on local SEO and content marketing",
    "additional_instructions": "Include industry-specific keywords and maintain a professional tone",
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2024-03-15T10:30:00Z"
  }
}

Update Campaign Notes Response

{
  "error": false,
  "messages": [
    "Campaign notes updated successfully"
  ],
  "pagination": {},
  "data": {
    "campaign_id": 12345,
    "writer_instructions": "Focus on local SEO and content marketing",
    "additional_instructions": "Include industry-specific keywords and maintain a professional tone",
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2024-03-15T10:30:00Z"
  }
}

Important Notes

• Campaign Stage ID: The campaign_stage_id field indicates the campaign stage (1-5), where 5 represents "Closed/Won" status
• Campaign Stages: Available stages include "Cold", "Warm", "Proposal", "Neg/Review", and "Closed/Won"
• Account Association: Each campaign is linked to a specific account via the account_id field
• Campaign Status: The status field indicates if the campaign is active (1) or inactive (0)
• PPC Budget: Campaigns can have PPC monthly budgets and invoice status tracking
• Service Declines: Campaigns track decline settings for GMB, reviews, and blog services
• Campaign Notes: Use the notes endpoints to manage writer instructions and additional instructions for campaigns
• Query Parameters: Campaign notes GET endpoint requires campaign_id as a query parameter
• Required Fields: Campaign notes PUT endpoint requires campaign_id, writer_instructions, and additional_instructions

Recommendations

• Use the campaigns endpoint to discover all accounts and their campaigns in your system
• Store account and campaign IDs for future reference and operations
• Implement proper error handling for campaign retrieval operations
• Consider pagination when dealing with large numbers of accounts and campaigns
• Use the returned data to build account and campaign management interfaces
• Campaign Notes Management: Use campaign notes to provide clear instructions for content writers
• Notes Best Practices: Keep writer instructions concise and specific to campaign goals
• Regular Updates: Update campaign notes as project requirements evolve
• Validation: Ensure all required fields are provided when updating campaign notes