ads API reference — Part 3

Embed

<a href="https://hermeticor.com/docs/ref-ads"><img src="https://hermeticor.com/docs/_api/public/orgs/5fcd8b3c-a27c-4688-972f-de710125592f/spaces/caf5dc05-15f7-4e0c-bdb8-ab29ede6211e/pages/c2535669-01a3-482f-a371-11a539962017/social-card.svg?v=3e7ae33eec8b" alt="ads" width="600" height="315"></a>

POSThttps://hermeticor.com/v1/ads/campaigns

Draft a campaign (budget, schedule, targeting, creative); nothing is sent until it is pushed

Request body

application/json

accountIdstringrequired

namestringrequired

objectivestring

traffic | leads | sales | awareness | engagement = traffic

dailyBudgetMinorintegerrequired

currencystringrequired

startAtstring

endAtstring

targetingobjectrequired

Show child parameters

countriesstring[]

= []

ageMininteger

ageMaxinteger

audienceIdsstring[]

= []

googleLocationIdsstring[]

= []

creativeobjectrequired

Show child parameters

headlinestringrequired

bodystringrequired

linkUrlstringrequired

imageUrlstring

ctastring

= LEARN_MORE

descriptionsstring[]

= []

adSetsAdSetsItem2[]

Show child parameters

namestringrequired

targetingobjectrequired

Show child parameters

countriesstring[]

= []

ageMininteger

ageMaxinteger

audienceIdsstring[]

= []

googleLocationIdsstring[]

= []

dailyBudgetMinorinteger

creativesCreative2[]required

Show child parameters

headlinestringrequired

bodystringrequired

linkUrlstringrequired

imageUrlstring

ctastring

= LEARN_MORE

descriptionsstring[]

= []

{
  "accountId": "string",
  "name": "string",
  "objective": "traffic",
  "dailyBudgetMinor": 0,
  "currency": "string",
  "startAt": "2024-01-01T00:00:00Z",
  "endAt": "2024-01-01T00:00:00Z",
  "targeting": {
    "countries": [],
    "ageMin": 0,
    "ageMax": 0,
    "audienceIds": [],
    "googleLocationIds": []
  },
  "creative": {
    "headline": "string",
    "body": "string",
    "linkUrl": "string",
    "imageUrl": "string",
    "cta": "LEARN_MORE",
    "descriptions": []
  },
  "adSets": [
    {
      "name": "string",
      "targeting": {
        "countries": [],
        "ageMin": 0,
        "ageMax": 0,
        "audienceIds": [],
        "googleLocationIds": []
      },
      "dailyBudgetMinor": 0,
      "creatives": [
        {
          "headline": "string",
          "body": "string",
          "linkUrl": "string",
          "imageUrl": "string",
          "cta": "LEARN_MORE",
          "descriptions": []
        }
      ]
    }
  ]
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/ads/campaigns" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"string","name":"string","objective":"traffic","dailyBudgetMinor":0,"currency":"string","startAt":"2024-01-01T00:00:00Z","endAt":"2024-01-01T00:00:00Z","targeting":{"countries":[],"ageMin":0,"ageMax":0,"audienceIds":[],"googleLocationIds":[]},"creative":{"headline":"string","body":"string","linkUrl":"string","imageUrl":"string","cta":"LEARN_MORE","descriptions":[]},"adSets":[{"name":"string","targeting":{"countries":[],"ageMin":0,"ageMax":0,"audienceIds":[],"googleLocationIds":[]},"dailyBudgetMinor":0,"creatives":[{"headline":"string","body":"string","linkUrl":"string","imageUrl":"string","cta":"LEARN_MORE","descriptions":[]}]}]}'

TypeScript

Python

PHP

Ruby

Java

Responses

201 Default Response

Example

{
  "accountId": "string",
  "name": "string",
  "objective": "traffic",
  "dailyBudgetMinor": 0,
  "currency": "string",
  "startAt": "string",
  "endAt": "string",
  "targeting": {
    "countries": [],
    "ageMin": 0,
    "ageMax": 0,
    "audienceIds": [],
    "googleLocationIds": []
  },
  "creative": {
    "headline": "string",
    "body": "string",
    "linkUrl": "string",
    "imageUrl": "string",
    "cta": "LEARN_MORE",
    "descriptions": []
  },
  "adSets": [
    {
      "name": "string",
      "targeting": {
        "countries": [],
        "ageMin": 0,
        "ageMax": 0,
        "audienceIds": [],
        "googleLocationIds": []
      },
      "dailyBudgetMinor": 0,
      "creatives": [
        {
          "headline": "string",
          "body": "string",
          "linkUrl": "string",
          "imageUrl": "string",
          "cta": "LEARN_MORE",
          "descriptions": []
        }
      ]
    }
  ],
  "id": "string",
  "status": "draft",
  "externalIds": {},
  "lastError": "string",
  "syncedAt": "string",
  "createdAt": "string"
}

Schema

accountIdstringrequired

namestringrequired

objectivestringrequired

traffic | leads | sales | awareness | engagement = traffic

dailyBudgetMinorintegerrequired

currencystringrequired

startAtstringrequired

endAtstringrequired

targetingobjectrequired

Show child parameters

countriesstring[]required

= []

ageMininteger

ageMaxinteger

audienceIdsstring[]required

= []

googleLocationIdsstring[]required

= []

creativeobjectrequired

Show child parameters

headlinestringrequired

bodystringrequired

linkUrlstringrequired

imageUrlstring

ctastringrequired

= LEARN_MORE

descriptionsstring[]required

= []

adSetsAdSetsItem[]

Show child parameters

namestringrequired

targetingobjectrequired

Show child parameters

countriesstring[]required

= []

ageMininteger

ageMaxinteger

audienceIdsstring[]required

= []

googleLocationIdsstring[]required

= []

dailyBudgetMinorinteger

creativesCreative[]required

Show child parameters

headlinestringrequired

bodystringrequired

linkUrlstringrequired

imageUrlstring

ctastringrequired

= LEARN_MORE

descriptionsstring[]required

= []

idstringrequired

statusstringrequired

draft | active | paused | archived | error

externalIdsobjectrequired

lastErrorstringrequired

syncedAtstringrequired

createdAtstringrequired

4XX Default Response

Example

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

detailsobject

5XX Default Response

Same as 4XX · POST /v1/ads/campaigns

GEThttps://hermeticor.com/v1/ads/campaigns/{id}

One campaign

Parameters

idstringpathrequired

Code samples

cURL

curl -X GET "https://hermeticor.com/v1/ads/campaigns/{id}" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/ads/campaigns

4XX Default Response

Same as 4XX · POST /v1/ads/campaigns

5XX Default Response

Same as 4XX · POST /v1/ads/campaigns

PATCHhttps://hermeticor.com/v1/ads/campaigns/{id}

Edit a draft campaign

Parameters

idstringpathrequired

Request body

application/json

namestring

objectivestring

traffic | leads | sales | awareness | engagement

dailyBudgetMinorinteger

currencystring

startAtstring

endAtstring

targetingobject

Show child parameters

countriesstring[]

= []

ageMininteger

ageMaxinteger

audienceIdsstring[]

= []

googleLocationIdsstring[]

= []

creativeobject

Show child parameters

headlinestringrequired

bodystringrequired

linkUrlstringrequired

imageUrlstring

ctastring

= LEARN_MORE

descriptionsstring[]

= []

adSetsAdSetsItem2[]

Show child parameters

namestringrequired

targetingobjectrequired

Show child parameters

countriesstring[]

= []

ageMininteger

ageMaxinteger

audienceIdsstring[]

= []

googleLocationIdsstring[]

= []

dailyBudgetMinorinteger

creativesCreative2[]required

Show child parameters

headlinestringrequired

bodystringrequired

linkUrlstringrequired

imageUrlstring

ctastring

= LEARN_MORE

descriptionsstring[]

= []

{
  "name": "string",
  "objective": "traffic",
  "dailyBudgetMinor": 0,
  "currency": "string",
  "startAt": "2024-01-01T00:00:00Z",
  "endAt": "2024-01-01T00:00:00Z",
  "targeting": {
    "countries": [],
    "ageMin": 0,
    "ageMax": 0,
    "audienceIds": [],
    "googleLocationIds": []
  },
  "creative": {
    "headline": "string",
    "body": "string",
    "linkUrl": "string",
    "imageUrl": "string",
    "cta": "LEARN_MORE",
    "descriptions": []
  },
  "adSets": [
    {
      "name": "string",
      "targeting": {
        "countries": [],
        "ageMin": 0,
        "ageMax": 0,
        "audienceIds": [],
        "googleLocationIds": []
      },
      "dailyBudgetMinor": 0,
      "creatives": [
        {
          "headline": "string",
          "body": "string",
          "linkUrl": "string",
          "imageUrl": "string",
          "cta": "LEARN_MORE",
          "descriptions": []
        }
      ]
    }
  ]
}

Code samples

cURL

curl -X PATCH "https://hermeticor.com/v1/ads/campaigns/{id}" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","objective":"traffic","dailyBudgetMinor":0,"currency":"string","startAt":"2024-01-01T00:00:00Z","endAt":"2024-01-01T00:00:00Z","targeting":{"countries":[],"ageMin":0,"ageMax":0,"audienceIds":[],"googleLocationIds":[]},"creative":{"headline":"string","body":"string","linkUrl":"string","imageUrl":"string","cta":"LEARN_MORE","descriptions":[]},"adSets":[{"name":"string","targeting":{"countries":[],"ageMin":0,"ageMax":0,"audienceIds":[],"googleLocationIds":[]},"dailyBudgetMinor":0,"creatives":[{"headline":"string","body":"string","linkUrl":"string","imageUrl":"string","cta":"LEARN_MORE","descriptions":[]}]}]}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/ads/campaigns

4XX Default Response

Same as 4XX · POST /v1/ads/campaigns

5XX Default Response

Same as 4XX · POST /v1/ads/campaigns

POSThttps://hermeticor.com/v1/ads/campaigns/{id}/push

Create the campaign on the platform (paused)

Parameters

idstringpathrequired

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/ads/campaigns/{id}/push" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/ads/campaigns

4XX Default Response

Same as 4XX · POST /v1/ads/campaigns

5XX Default Response

Same as 4XX · POST /v1/ads/campaigns

POSThttps://hermeticor.com/v1/ads/campaigns/{id}/status

Activate, pause or archive the campaign on the platform

Parameters

idstringpathrequired

Request body

application/json

statusstringrequired

active | paused | archived

{
  "status": "active"
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/ads/campaigns/{id}/status" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/ads/campaigns

4XX Default Response

Same as 4XX · POST /v1/ads/campaigns

5XX Default Response

Same as 4XX · POST /v1/ads/campaigns

POSThttps://hermeticor.com/v1/ads/campaigns/{id}/budget

Change the daily budget and end date

Parameters

idstringpathrequired

Request body

application/json

dailyBudgetMinorintegerrequired

endAtstring

= null

{
  "dailyBudgetMinor": 0,
  "endAt": null
}

Code samples

cURL

curl -X POST "https://hermeticor.com/v1/ads/campaigns/{id}/budget" \
  -H "Authorization: Bearer $HERMETICOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dailyBudgetMinor":0,"endAt":null}'

TypeScript

Python

PHP

Ruby

Java