API Reference - Marketing Offers

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108104

← Back to API Reference | Getting Started

Marketing Offers

Marketing Offers represent partner promotions and sponsored placements displayed to members on your directory site. Each offer includes branding, messaging, a call-to-action, and an optional affiliate registration link.

Model name in URL: marketing_offers — DB table: marketing_offers

The Marketing Offer Object

FieldTypeDescription
idintegerUnique offer ID (primary key, read-only)
typestringOffer category; typically listing for member-facing promotions
categorystringOptional sub-category to group or filter offers
orderintegerDisplay sort order; lower numbers appear first
statusintegerWhether the offer is active and visible: 1 active, 0 inactive
namestringDisplay name for the offer (shown to members)
system_namestringInternal identifier for this offer; used in templates and logic
logo_filenamestringFilename of the partner logo image (relative to the site's uploads directory)
headlinetextPrimary headline or title text displayed in the offer widget
descriptiontextBody text describing the offer or partner
offertextPromotional offer details or discount description (EG "Save 20% for 3 months")
cta_urlstringCall-to-action URL members are sent to when they click the offer
cta_textstringCall-to-action button label (EG Get Started, Learn More)
affiliate_registration_urlstringAffiliate or partner sign-up URL for tracking referrals from this offer

List Marketing Offers

GET /api/v2/marketing_offers/get

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/marketing_offers/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "id": "1",
      "type": "listing",
      "category": null,
      "order": "0",
      "status": "1",
      "name": "Acme Website Builder",
      "system_name": "acme-websites",
      "logo_filename": "acme-logo.png",
      "headline": "Build your website in minutes",
      "description": "Acme Website Builder makes it easy to create a professional site.",
      "offer": "Save 20% for 3 months with code DIRECTORY20",
      "cta_url": "https://acme.example.com/partner",
      "cta_text": "Get Started",
      "affiliate_registration_url": "https://acme.example.com/affiliates/register"
    }
  ],
  "total": "5",
  "current_page": 1,
  "total_pages": 1,
  "next_page": ""
}

Retrieve a Marketing Offer

GET /api/v2/marketing_offers/get/{id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/marketing_offers/get/1" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "id": "1",
      "type": "listing",
      "category": null,
      "order": "0",
      "status": "1",
      "name": "Acme Website Builder",
      "system_name": "acme-websites",
      "logo_filename": "acme-logo.png",
      "headline": "Build your website in minutes",
      "description": "Acme Website Builder makes it easy to create a professional site.",
      "offer": "Save 20% for 3 months with code DIRECTORY20",
      "cta_url": "https://acme.example.com/partner",
      "cta_text": "Get Started",
      "affiliate_registration_url": "https://acme.example.com/affiliates/register"
    }
  ],
  "total": "5",
  "current_page": 1,
  "total_pages": 1
}

Create a Marketing Offer

POST /api/v2/marketing_offers/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/marketing_offers/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "type=listing" \
  -d "name=Acme+Website+Builder" \
  -d "system_name=acme-websites" \
  -d "headline=Build+your+website+in+minutes" \
  -d "description=Acme+Website+Builder+makes+it+easy+to+create+a+professional+site." \
  -d "offer=Save+20%25+for+3+months+with+code+DIRECTORY20" \
  -d "cta_url=https://acme.example.com/partner" \
  -d "cta_text=Get+Started" \
  -d "status=1" \
  -d "order=1"

Example Response

Copy
{
  "status": "success",
  "message": {
    "id": "6",
    "type": "listing",
    "category": null,
    "order": "1",
    "status": "1",
    "name": "Acme Website Builder",
    "system_name": "acme-websites",
    "logo_filename": null,
    "headline": "Build your website in minutes",
    "description": "Acme Website Builder makes it easy to create a professional site.",
    "offer": "Save 20% for 3 months with code DIRECTORY20",
    "cta_url": "https://acme.example.com/partner",
    "cta_text": "Get Started",
    "affiliate_registration_url": null
  }
}

Update a Marketing Offer

PUT /api/v2/marketing_offers/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/marketing_offers/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "id=6" \
  -d "headline=Launch+your+site+today" \
  -d "cta_text=Start+Free+Trial" \
  -d "affiliate_registration_url=https://acme.example.com/affiliates/register"

Example Response

Copy
{
  "status": "success",
  "message": {
    "id": "6",
    "type": "listing",
    "category": null,
    "order": "1",
    "status": "1",
    "name": "Acme Website Builder",
    "system_name": "acme-websites",
    "logo_filename": null,
    "headline": "Launch your site today",
    "description": "Acme Website Builder makes it easy to create a professional site.",
    "offer": "Save 20% for 3 months with code DIRECTORY20",
    "cta_url": "https://acme.example.com/partner",
    "cta_text": "Start Free Trial",
    "affiliate_registration_url": "https://acme.example.com/affiliates/register"
  }
}

Delete a Marketing Offer

DELETE /api/v2/marketing_offers/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/marketing_offers/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "id=6"

Example Response

Copy
{
  "status": "success",
  "message": "marketing_offers record was deleted"
}