ads API reference

Embed

<a href="https://hermetica.15.204.158.166.sslip.io/docs/ref-ads"><img src="https://hermetica.15.204.158.166.sslip.io/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>

GEThttps://hermetica.15.204.158.166.sslip.io/v1/ads/accounts

Connected ad accounts

Parameters

limitintegerquery

Page size; omitted returns the whole list

cursorstringquery

Opaque: the nextCursor of the previous page

Code samples

cURL

curl -X GET "https://hermetica.15.204.158.166.sslip.io/v1/ads/accounts" \
  -H "Authorization: Bearer $SSLIP_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "items": [
    {
      "id": "string",
      "platform": "meta",
      "name": "string",
      "externalId": "string",
      "config": {},
      "status": "string",
      "lastError": "string",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "string"
}

Schema

itemsobject[]required

Show child parameters

idstringrequired

platformstringrequired

namestringrequired

externalIdstringrequired

configobjectrequired

statusstringrequired

lastErrorstringrequired

createdAtstringrequired

nextCursorstringrequired

4XX Default Response

Example

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

Schema

errorobjectrequired

Show child parameters

codestringrequired

messagestringrequired

detailsobject

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

POSThttps://hermetica.15.204.158.166.sslip.io/v1/ads/accounts

Connect an ad account (credentials are sealed and never returned)

Request body

application/json

platformstringrequired

namestringrequired

externalIdstringrequired

credentialsobjectrequired

configobject

Show child parameters

pixelIdstring

pixelCodestring

loginCustomerIdstring

apiVersionstring

{
  "platform": "meta",
  "name": "string",
  "externalId": "string",
  "credentials": {},
  "config": {
    "pixelId": "string",
    "pixelCode": "string",
    "loginCustomerId": "string",
    "apiVersion": "string"
  }
}

Code samples

cURL

curl -X POST "https://hermetica.15.204.158.166.sslip.io/v1/ads/accounts" \
  -H "Authorization: Bearer $SSLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"platform":"meta","name":"string","externalId":"string","credentials":{},"config":{"pixelId":"string","pixelCode":"string","loginCustomerId":"string","apiVersion":"string"}}'

TypeScript

Python

PHP

Ruby

Java

Responses

201 Default Response

Example

{
  "id": "string",
  "platform": "meta",
  "name": "string",
  "externalId": "string",
  "config": {},
  "status": "string",
  "lastError": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

platformstringrequired

namestringrequired

externalIdstringrequired

configobjectrequired

statusstringrequired

lastErrorstringrequired

createdAtstringrequired

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

DELETEhttps://hermetica.15.204.158.166.sslip.io/v1/ads/accounts/{id}

Disconnect an ad account (its audience syncs stop; audiences stay in the platform)

Parameters

idstringpathrequired

Code samples

cURL

curl -X DELETE "https://hermetica.15.204.158.166.sslip.io/v1/ads/accounts/{id}" \
  -H "Authorization: Bearer $SSLIP_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "ok": true
}

Schema

okbooleanrequired

true

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

PATCHhttps://hermetica.15.204.158.166.sslip.io/v1/ads/accounts/{id}

Change an ad account's pixel / API settings

Parameters

idstringpathrequired

Request body

application/json

configobjectrequired

{
  "config": {}
}

Code samples

cURL

curl -X PATCH "https://hermetica.15.204.158.166.sslip.io/v1/ads/accounts/{id}" \
  -H "Authorization: Bearer $SSLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config":{}}'

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/ads/accounts

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

GEThttps://hermetica.15.204.158.166.sslip.io/v1/ads/audiences

Segment -> ad audience syncs

Parameters

segmentIdstringquery

accountIdstringquery

limitintegerquery

Page size; omitted returns the whole list

cursorstringquery

Opaque: the nextCursor of the previous page

Code samples

cURL

curl -X GET "https://hermetica.15.204.158.166.sslip.io/v1/ads/audiences" \
  -H "Authorization: Bearer $SSLIP_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Example

{
  "items": [
    {
      "id": "string",
      "accountId": "string",
      "segmentId": "string",
      "name": "string",
      "externalAudienceId": "string",
      "schedule": "manual",
      "onlyMarketing": true,
      "enabled": true,
      "status": "string",
      "lastSyncedAt": "2024-01-01T00:00:00Z",
      "lastError": "string",
      "memberCount": 0,
      "lastAdded": 0,
      "lastRemoved": 0,
      "matchRate": "string",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "string"
}

Schema

itemsobject[]required

Show child parameters

idstringrequired

accountIdstringrequired

segmentIdstringrequired

namestringrequired

externalAudienceIdstringrequired

schedulestringrequired

manual | hourly | daily

onlyMarketingbooleanrequired

enabledbooleanrequired

statusstringrequired

lastSyncedAtstringrequired

lastErrorstringrequired

memberCountintegerrequired

lastAddedintegerrequired

lastRemovedintegerrequired

matchRatestringrequired

createdAtstringrequired

nextCursorstringrequired

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

POSThttps://hermetica.15.204.158.166.sslip.io/v1/ads/audiences

Sync a segment to an ad platform audience; the first run starts at once

Request body

application/json

accountIdstringrequired

segmentIdstringrequired

namestringrequired

schedulestring

manual | hourly | daily = daily

onlyMarketingboolean

= true

existingAudienceIdstring

{
  "accountId": "string",
  "segmentId": "string",
  "name": "string",
  "schedule": "daily",
  "onlyMarketing": true,
  "existingAudienceId": "string"
}

Code samples

cURL

curl -X POST "https://hermetica.15.204.158.166.sslip.io/v1/ads/audiences" \
  -H "Authorization: Bearer $SSLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accountId":"string","segmentId":"string","name":"string","schedule":"daily","onlyMarketing":true,"existingAudienceId":"string"}'

TypeScript

Python

PHP

Ruby

Java

Responses

201 Default Response

Example

{
  "id": "string",
  "accountId": "string",
  "segmentId": "string",
  "name": "string",
  "externalAudienceId": "string",
  "schedule": "manual",
  "onlyMarketing": true,
  "enabled": true,
  "status": "string",
  "lastSyncedAt": "2024-01-01T00:00:00Z",
  "lastError": "string",
  "memberCount": 0,
  "lastAdded": 0,
  "lastRemoved": 0,
  "matchRate": "string",
  "createdAt": "2024-01-01T00:00:00Z"
}

Schema

idstringrequired

accountIdstringrequired

segmentIdstringrequired

namestringrequired

externalAudienceIdstringrequired

schedulestringrequired

manual | hourly | daily

onlyMarketingbooleanrequired

enabledbooleanrequired

statusstringrequired

lastSyncedAtstringrequired

lastErrorstringrequired

memberCountintegerrequired

lastAddedintegerrequired

lastRemovedintegerrequired

matchRatestringrequired

createdAtstringrequired

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

GEThttps://hermetica.15.204.158.166.sslip.io/v1/ads/audiences/{id}

One audience sync

Parameters

idstringpathrequired

Code samples

cURL

curl -X GET "https://hermetica.15.204.158.166.sslip.io/v1/ads/audiences/{id}" \
  -H "Authorization: Bearer $SSLIP_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 201 · POST /v1/ads/audiences

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

DELETEhttps://hermetica.15.204.158.166.sslip.io/v1/ads/audiences/{id}

Stop syncing (the platform audience is left as it is)

Parameters

idstringpathrequired

Code samples

cURL

curl -X DELETE "https://hermetica.15.204.158.166.sslip.io/v1/ads/audiences/{id}" \
  -H "Authorization: Bearer $SSLIP_API_KEY"

TypeScript

Python

PHP

Ruby

Java

Responses

200 Default Response

Same as 200 · DELETE /v1/ads/accounts/{id}

4XX Default Response

Same as 4XX · GET /v1/ads/accounts

5XX Default Response

Same as 4XX · GET /v1/ads/accounts

PATCHhttps://hermetica.15.204.158.166.sslip.io/v1/ads/audiences/{id}

Change schedule, consent filter or pause a sync

Parameters

idstringpathrequired

Request body

application/json

namestring

schedulestring

manual | hourly | daily

onlyMarketingboolean

enabledboolean

{
  "name": "string",
  "schedule": "manual",
  "onlyMarketing": true,
  "enabled": true
}

Code samples

cURL

curl -X PATCH "https://hermetica.15.204.158.166.sslip.io/v1/ads/audiences/{id}" \
  -H "Authorization: Bearer $SSLIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"string","schedule":"manual","onlyMarketing":true,"enabled":true}'

TypeScript

Python

PHP

Ruby

Java