Synupv1
Create a key
v1Resources/Connections

Connections

Manage your agency's connected publisher and social accounts, their ad accounts, boost configuration presets, and connected business apps.

Returns your agency's connected publisher/social accounts (Google, Facebook, Instagram, LinkedIn, TikTok, and others), optionally filtered by client or platform.

List connected accounts

get/api/v1/connections
connections:read
Query parameters
clientIdstringoptional
Restrict results to one client. When your key is scoped to specific clients, results are always pre-filtered to those clients even if this is omitted.
platformstringoptional
Restrict results to one platform, e.g. facebook, google.
credentialsValidbooleanoptional
Restrict to accounts whose stored credentials are (true) or aren't (false) currently valid.
fetchStatusstringoptional
Restrict to accounts with this fetch status.
cursorstringoptional
Pagination cursor from a previous response's nextCursor.
limitintegeroptional
Max accounts to return, 1–100. Defaults to 20.
Response
dataobjectoptional
accountsarray of objectoptional
The matching connected accounts.
idstringoptional
Unique identifier for the connected account.
platformstringoptional
The platform this account connects to, e.g. google, facebook, instagram.
displayNamestringoptional
Display name of the connected account.
providerAccountIdstringoptional
The platform's own identifier for this account.
credentialsValidbooleanoptional
Whether the stored credentials are currently valid.
fetchStatusstringoptional
Current fetch status for this account, e.g. idle, fetching.
fetchErrorstringoptional
The last fetch error message, or null.
errorTagstringoptional
A short machine-readable error code, or null.
gmbGroupIdsarray of stringoptional
Google Business Profile group ids associated with this account, if any.
expiresAtstringoptional
When this account's access token expires, as an ISO 8601 timestamp, or null.
dataAccessExpiresAtstringoptional
When Meta's data-access window for this account expires, as an ISO 8601 timestamp, or null.
channelstringoptional
The channel this connection was made through.
clientIdstringoptional
ID of the client this account belongs to, or null for an agency-wide connection.
synupLocationIdstringoptional
Legacy location identifier. Deprecated — prefer clientLocationId.
clientLocationIdstringoptional
ID of the location this account is bound to, or null. Prefer this over synupLocationId.
fetchedListingsCountnumberoptional
Number of listings this account has fetched.
lastFetchedAtstringoptional
When this account last completed a fetch, as an ISO 8601 timestamp, or null.
connectionStatusstring (CONNECTED | MISSING | RENEW | DISCONNECTED | SUSPENDED | SUGGESTED_MATCH)optional
Overall health of this connection: CONNECTED, MISSING, RENEW, DISCONNECTED, SUSPENDED, or SUGGESTED_MATCH.
createdAtstringoptional
When this account was connected, as an ISO 8601 timestamp.
updatedAtstringoptional
When this account was last updated, as an ISO 8601 timestamp.
nextCursorstringoptional
Pagination cursor for the next page, or null when there are no more results.
totalCountnumberoptional
Total number of accounts matching the request.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections
Your API key
clientId
platform
credentialsValid
fetchStatus
cursor
limit
{
  "data": {
    "accounts": [
      {
        "id": "conn_1",
        "platform": "google",
        "displayName": "Acme Dental — Google",
        "providerAccountId": "112233445566",
        "credentialsValid": true,
        "fetchStatus": "ok",
        "fetchError": null,
        "errorTag": null,
        "gmbGroupIds": [],
        "expiresAt": null,
        "dataAccessExpiresAt": "2026-05-01T00:00:00.000Z",
        "channel": "local",
        "clientId": "cli_123",
        "synupLocationId": null,
        "clientLocationId": "loc_456"
      }
    ],
    "nextCursor": null,
    "totalCount": 1
  }
}
v1Resources/Connections/getGet a connected-accounts summary

How many of this client's (or the whole agency's) locations have Google/Facebook connected vs. not. Scope to a subset with tags.

Get a connected-accounts summary

get/api/v1/connections/summary
connections:read
Query parameters
clientIdstringoptional
Limit to one client's locations.
tagsstringoptional
Comma-separated location tag names — only locations carrying at least one of these are counted.
Response
dataobjectoptional
totalnumberoptional
Total locations in scope.
googleobjectoptional
connectednumberoptional
Locations with this publisher connected.
notConnectednumberoptional
Locations without this publisher connected.
facebookobjectoptional
connectednumberoptional
Locations with this publisher connected.
notConnectednumberoptional
Locations without this publisher connected.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections/summary
Your API key
clientId
tags
{
  "data": {
    "total": 5,
    "google": {
      "connected": 3,
      "notConnected": 2
    },
    "facebook": {
      "connected": 1,
      "notConnected": 4
    }
  }
}
v1Resources/Connections/getGet a Google connect URL

Returns a Google OAuth authorize URL to open in a browser to connect this location's Google Business Profile. This endpoint can't complete the connection itself — Google's consent screen requires an interactive human.

Get a Google connect URL

get/api/v1/connections/google/connect-url
connections:write
Query parameters
locationIdstringrequired
The location to connect.
clientIdstringoptional
The location's client. Only needed to disambiguate when your key is scoped to specific clients.
returnUrlstringoptional
In-app path to land on after the human completes the consent screen. Defaults to "/".
Response
dataobjectoptional
providerstring (google | facebook)optional
Which publisher this URL connects.
locationIdstringoptional
The location this connection will be paired to once approved.
urlstringoptional
The authorize URL — open it in a browser under the account owner's control.
notestringoptional
Explains there's no callback to your integration; poll GET /api/v1/connections afterward.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections/google/connect-url
Your API key
locationId *
clientId
returnUrl
{
  "data": {
    "provider": "google",
    "locationId": "loc_456",
    "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&response_type=code&scope=...&state=...",
    "note": "Open this URL in a browser under the account owner's control. There is no callback to your integration — once approved, poll GET /api/v1/connections to see the new connection."
  }
}
v1Resources/Connections/getGet a Facebook connect URL

Returns a Facebook OAuth authorize URL to open in a browser to connect this location's Facebook Page. This endpoint can't complete the connection itself — Facebook's consent screen requires an interactive human.

Get a Facebook connect URL

get/api/v1/connections/facebook/connect-url
connections:write
Query parameters
locationIdstringrequired
The location to connect.
clientIdstringoptional
The location's client. Only needed to disambiguate when your key is scoped to specific clients.
returnUrlstringoptional
In-app path to land on after the human completes the consent screen. Defaults to "/".
Response
dataobjectoptional
providerstring (google | facebook)optional
Which publisher this URL connects.
locationIdstringoptional
The location this connection will be paired to once approved.
urlstringoptional
The authorize URL — open it in a browser under the account owner's control.
notestringoptional
Explains there's no callback to your integration; poll GET /api/v1/connections afterward.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections/facebook/connect-url
Your API key
locationId *
clientId
returnUrl
{
  "data": {
    "provider": "facebook",
    "locationId": "loc_456",
    "url": "https://www.facebook.com/v19.0/dialog/oauth?client_id=...&redirect_uri=...&scope=...&state=...&response_type=code",
    "note": "Open this URL in a browser under the account owner's control. There is no callback to your integration — once approved, poll GET /api/v1/connections to see the new connection."
  }
}
v1Resources/Connections/getList ad accounts

Returns the paid-social ad accounts available on one connected account (Facebook, Instagram, LinkedIn, or TikTok).

List ad accounts

get/api/v1/connections/ad-accounts
connections:read
Query parameters
connectionIdstringrequired
The connected account to look up. Required. Look it up with GET /api/v1/connections.
Response
dataobjectoptional
adAccountsarray of objectoptional
The ad accounts available on this connected account.
idstringoptional
Unique identifier for the ad account.
connectionIdstringoptional
ID of the connected account this ad account belongs to.
platformAccountIdstringoptional
The platform's own identifier for this ad account, e.g. act_226123609900306 for Meta.
namestringoptional
Display name of the ad account.
platformstringoptional
Platform this ad account belongs to: facebook, instagram, linkedin, or tiktok.
statusstring (active | disabled | unsettled | pending_review)optional
Platform-reported status: active, disabled, unsettled, or pending_review.
isSelectedbooleanoptional
Whether this is the ad account currently selected for boosting on this connection.
currencystringoptional
Currency this ad account bills in, or null.
archivedbooleanoptional
Whether this ad account has been archived.
createdAtstringoptional
When this ad account was first synced, as an ISO 8601 timestamp.
updatedAtstringoptional
When this ad account was last synced, as an ISO 8601 timestamp.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections/ad-accounts
Your API key
connectionId *
{
  "data": {
    "adAccounts": [
      {
        "id": "adacct_1",
        "connectionId": "conn_1",
        "platformAccountId": "act_549988676430053",
        "name": "Acme Dental Ads",
        "platform": "facebook",
        "status": "active",
        "isSelected": true,
        "currency": "USD",
        "archived": false,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}
v1Resources/Connections/postSync ad accounts

Forces an immediate re-fetch of a connected account's ad accounts from the platform, instead of waiting for the daily background sync. Returns the refreshed list.

Sync ad accounts

post/api/v1/connections/ad-accounts/sync
connections:write
Request body
connectionIdstringrequired
The connected account to sync. Required. Look it up with GET /api/v1/connections.
Response
dataobjectoptional
adAccountsarray of objectoptional
The ad accounts available on this connected account.
idstringoptional
Unique identifier for the ad account.
connectionIdstringoptional
ID of the connected account this ad account belongs to.
platformAccountIdstringoptional
The platform's own identifier for this ad account, e.g. act_226123609900306 for Meta.
namestringoptional
Display name of the ad account.
platformstringoptional
Platform this ad account belongs to: facebook, instagram, linkedin, or tiktok.
statusstring (active | disabled | unsettled | pending_review)optional
Platform-reported status: active, disabled, unsettled, or pending_review.
isSelectedbooleanoptional
Whether this is the ad account currently selected for boosting on this connection.
currencystringoptional
Currency this ad account bills in, or null.
archivedbooleanoptional
Whether this ad account has been archived.
createdAtstringoptional
When this ad account was first synced, as an ISO 8601 timestamp.
updatedAtstringoptional
When this ad account was last synced, as an ISO 8601 timestamp.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/ad-accounts/sync
Your API key
Request body*
{
  "data": {
    "adAccounts": [
      {
        "id": "adacct_1",
        "connectionId": "conn_1",
        "platformAccountId": "act_549988676430053",
        "name": "Acme Dental Ads",
        "platform": "facebook",
        "status": "active",
        "isSelected": false,
        "currency": "USD",
        "archived": false,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-02-01T09:00:00.000Z"
      }
    ]
  }
}
v1Resources/Connections/postSelect an ad account

Chooses which of a connected account's ad accounts is used when boosting posts. Only one ad account can be selected per connected account at a time.

Select an ad account

post/api/v1/connections/ad-accounts/select
connections:write
Request body
connectionIdstringrequired
The connected account that owns the ad account. Required. Look it up with GET /api/v1/connections.
adAccountIdstringrequired
The ad account to select. Must belong to connectionId. Required.
Response
dataobjectoptional
selectedbooleanoptional
Always true on success.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/ad-accounts/select
Your API key
Request body*
{
  "data": {
    "selected": true
  }
}
v1Resources/Connections/postAssign a listing to a location

Pairs an already-connected account's already-fetched listing to a location with no connection of its own yet. Not a fresh OAuth grant — caId must already be a connected account; this reuses that login. Google and Facebook only.

Assign a listing to a location

post/api/v1/connections/locations/assign
connections:write
Request body
platformstring (google | facebook)required
The platform: google or facebook. Required.
caIdstringrequired
The already-connected account to pair. Required.
locationIdstringrequired
The location to assign this listing to. Required.
platformResourceNamestringrequired
The listing's resource name/id on the platform. Required.
platformPageNamestringrequired
The listing's display name on the platform. Required.
Response
dataobjectoptional
idstringoptional
Unique identifier for the resulting connection.
platformstring (google | facebook)optional
The platform the listing was paired on.
synupLocationIdstringoptional
The location's legacy Synup id, or null for a native location.
clientLocationIdstringoptional
The location's id.
platformResourceNamestringoptional
The listing's resource name/id on the platform.
platformPageNamestringoptional
The listing's display name on the platform.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/locations/assign
Your API key
Request body*
{
  "data": {
    "id": "listing_1",
    "platform": "google",
    "synupLocationId": null,
    "clientLocationId": "loc_456",
    "platformResourceName": "accounts/123/locations/456",
    "platformPageName": "Acme Dental — Downtown"
  }
}
v1Resources/Connections/postConfirm a suggested match

Confirms a NAP-scoring suggestion, creating a location-level connection from a fetched listing already matched to a Synup location. Fails if the listing has no matched location (400), is already connected (409), or the location already has a connection on that platform (409).

Confirm a suggested match

post/api/v1/connections/locations/confirm-match
connections:write
Request body
fetchedListingIdstringrequired
The fetched listing to confirm. Required.
Response
dataobjectoptional
idstringoptional
Unique identifier for the resulting connection.
platformstring (google | facebook)optional
The platform the listing was paired on.
synupLocationIdstringoptional
The location's legacy Synup id, or null for a native location.
clientLocationIdstringoptional
The location's id.
platformResourceNamestringoptional
The listing's resource name/id on the platform.
platformPageNamestringoptional
The listing's display name on the platform.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
409The request conflicts with the current state of the resource — for example, changing the email or phone of a recipient who has already been messaged, or a team invite that was already accepted (or hasn't been accepted yet).
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/locations/confirm-match
Your API key
Request body*
{
  "data": {
    "id": "listing_1",
    "platform": "google",
    "synupLocationId": null,
    "clientLocationId": "loc_456",
    "platformResourceName": "accounts/123/locations/456",
    "platformPageName": "Acme Dental — Downtown"
  }
}
v1Resources/Connections/postRequest new match suggestions

Re-runs NAP (name/address/phone) match scoring on a connected account's already-fetched listings. Does not re-fetch from the platform — pair with POST /api/v1/connections/fetch-listings for that. Rate-limited to once per 24 hours per account; a call inside the window returns 429 with a retryAt timestamp.

Request new match suggestions

post/api/v1/connections/request-matches
connections:write
Request body
connectionIdstringrequired
The connected account to re-score. Required. Look it up with GET /api/v1/connections.
Response
dataobjectoptional
scorednumberoptional
Number of listings re-scored.
messagestringoptional
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/request-matches
Your API key
Request body*
{
  "data": {
    "scored": 4,
    "message": null
  }
}
v1Resources/Connections/postForce-refetch an account's listings

Forces an immediate re-fetch of a connected account's listings straight from the platform — not just a re-score of what's already stored, which is POST /api/v1/connections/request-matches. Runs synchronously; the response confirms the fetch already completed.

Force-refetch an account's listings

post/api/v1/connections/fetch-listings
connections:write
Request body
connectionIdstringrequired
The connected account to re-fetch. Required. Look it up with GET /api/v1/connections.
Response
dataobjectoptional
statusstringoptional
countnumberoptional
Number of listings fetched.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/fetch-listings
Your API key
Request body*
{
  "data": {
    "status": "completed",
    "count": 4
  }
}
v1Resources/Connections/getList boost configs

Returns the saved boost configurations (reusable targeting and budget presets for boosting a post) on one connected account.

List boost configs

get/api/v1/connections/boost-configs
connections:read
Query parameters
connectionIdstringrequired
The connected account to look up. Required. Look it up with GET /api/v1/connections.
Response
dataobjectoptional
boostConfigsarray of objectoptional
The saved boost configurations on this connected account.
idstringoptional
Unique identifier for the boost config.
connectionIdstringoptional
ID of the connected account this boost config belongs to.
adAccountIdstringoptional
ID of the ad account this boost config spends from.
namestringoptional
Name of this preset.
platformstringoptional
Platform this boost config runs on, matching its connected account.
targetingobjectoptional
Targeting settings for this preset.
ageMinnumberoptional
Minimum audience age.
ageMaxnumberoptional
Maximum audience age.
gendersarray of numberoptional
Audience genders to target: 1 for male, 2 for female.
geoLocationsobjectoptional
Geographic targeting: countries, regions, cities, and/or zip codes.
interestsarray of objectoptional
Interest categories to target.
publisherPlatformsarray of stringoptional
Which platform surfaces to target, e.g. ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)optional
Restrict the audience to people who like the page (fans) or their friends too (fans_of_fans).
dailyBudgetnumberoptional
Daily budget, in the platform's minor currency unit (e.g. cents).
durationDaysnumberoptional
How many days the boost runs once applied.
delayHoursnumberoptional
Hours to wait after a post is published before boosting it.
publisherPlatformsarray of stringoptional
Which platform surfaces this preset boosts on.
archivedbooleanoptional
Whether this preset has been archived.
createdAtstringoptional
When this preset was created, as an ISO 8601 timestamp.
updatedAtstringoptional
When this preset was last updated, as an ISO 8601 timestamp.
adAccountobjectoptional
A short summary of the ad account this preset spends from, or null.
platformAccountIdstringoptional
The platform's own identifier for that ad account.
namestringoptional
Display name of that ad account.
currencystringoptional
Currency that ad account bills in, or null.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections/boost-configs
Your API key
connectionId *
{
  "data": {
    "boostConfigs": [
      {
        "id": "boost_1",
        "connectionId": "conn_1",
        "adAccountId": "adacct_1",
        "name": "Local awareness — $10/day",
        "platform": "facebook",
        "targeting": {
          "ageMin": 25,
          "ageMax": 55,
          "genders": [],
          "geoLocations": {
            "countries": [],
            "regions": [],
            "cities": [],
            "zips": []
          },
          "interests": [],
          "publisherPlatforms": [
            "facebook"
          ]
        },
        "dailyBudget": 10,
        "durationDays": 7,
        "delayHours": 0,
        "publisherPlatforms": [
          "facebook"
        ],
        "archived": false,
        "createdAt": "2026-01-15T10:00:00.000Z",
        "updatedAt": "2026-01-15T10:00:00.000Z"
      }
    ]
  }
}
v1Resources/Connections/postCreate a boost config

Saves a new reusable boost configuration (targeting, daily budget, and duration) on a connected account's ad account. This only stores a preset for later use — it does not itself boost a post, submit anything to the ad platform, or spend any money. Money is only spent when this saved config is later applied to boost a specific post.

Create a boost config

post/api/v1/connections/boost-configs
connections:write
Request body
connectionIdstringrequired
The connected account to attach this boost config to. Required. Look it up with GET /api/v1/connections.
adAccountIdstringrequired
The ad account to spend from when this config is used. Must belong to connectionId. Required.
namestringrequired
A name for this preset, shown when picking it later. Required.
targetingobjectoptional
All fields are optional. An empty object targets the platform's broadest default audience.
ageMinnumberoptional
Minimum audience age.
ageMaxnumberoptional
Maximum audience age.
gendersarray of numberoptional
Audience genders to target: 1 for male, 2 for female.
geoLocationsobjectoptional
Geographic targeting: countries, regions, cities, and/or zip codes.
countriesarray of stringoptional
regionsarray of objectoptional
keystringoptional
namestringoptional
citiesarray of objectoptional
keystringoptional
namestringoptional
radiusnumberoptional
distanceUnitstringoptional
zipsarray of objectoptional
keystringoptional
namestringoptional
interestsarray of objectoptional
Interest categories to target.
idstringoptional
namestringoptional
publisherPlatformsarray of stringoptional
Which platform surfaces to target, e.g. ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)optional
Restrict the audience to people who like the page (fans) or their friends too (fans_of_fans).
dailyBudgetnumberrequired
Daily budget, in the platform's minor currency unit (e.g. cents). Must be positive. Required.
durationDaysnumberrequired
How many days the boost should run once applied. Must be positive. Required.
delayHoursnumberoptional
Hours to wait after a post is published before boosting it. Defaults to 0.
publisherPlatformsarray of stringoptional
Which platform surfaces to boost on, e.g. ["facebook", "instagram"].
Response
dataobjectoptional
boostConfigobjectoptional
idstringoptional
Unique identifier for the boost config.
connectionIdstringoptional
ID of the connected account this boost config belongs to.
adAccountIdstringoptional
ID of the ad account this boost config spends from.
namestringoptional
Name of this preset.
platformstringoptional
Platform this boost config runs on, matching its connected account.
targetingobjectoptional
Targeting settings for this preset.
ageMinnumberoptional
Minimum audience age.
ageMaxnumberoptional
Maximum audience age.
gendersarray of numberoptional
Audience genders to target: 1 for male, 2 for female.
geoLocationsobjectoptional
Geographic targeting: countries, regions, cities, and/or zip codes.
interestsarray of objectoptional
Interest categories to target.
publisherPlatformsarray of stringoptional
Which platform surfaces to target, e.g. ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)optional
Restrict the audience to people who like the page (fans) or their friends too (fans_of_fans).
dailyBudgetnumberoptional
Daily budget, in the platform's minor currency unit (e.g. cents).
durationDaysnumberoptional
How many days the boost runs once applied.
delayHoursnumberoptional
Hours to wait after a post is published before boosting it.
publisherPlatformsarray of stringoptional
Which platform surfaces this preset boosts on.
archivedbooleanoptional
Whether this preset has been archived.
createdAtstringoptional
When this preset was created, as an ISO 8601 timestamp.
updatedAtstringoptional
When this preset was last updated, as an ISO 8601 timestamp.
adAccountobjectoptional
A short summary of the ad account this preset spends from, or null.
platformAccountIdstringoptional
The platform's own identifier for that ad account.
namestringoptional
Display name of that ad account.
currencystringoptional
Currency that ad account bills in, or null.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/boost-configs
Your API key
Request body*
{
  "data": {
    "boostConfig": {
      "id": "boost_1",
      "connectionId": "conn_1",
      "adAccountId": "adacct_1",
      "name": "Local awareness — $10/day",
      "platform": "facebook",
      "targeting": {
        "ageMin": 25,
        "ageMax": 55,
        "genders": [],
        "publisherPlatforms": [
          "facebook"
        ]
      },
      "dailyBudget": 10,
      "durationDays": 7,
      "delayHours": 0,
      "publisherPlatforms": [
        "facebook"
      ],
      "archived": false,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  }
}
v1Resources/Connections/postUpdate a boost config

Edits an existing, non-archived boost configuration. Only the fields you provide are changed.

Update a boost config

post/api/v1/connections/boost-configs/update
connections:write
Request body
connectionIdstringrequired
The connected account that owns the boost config. Required. Look it up with GET /api/v1/connections.
configIdstringrequired
The boost config to update. Must belong to connectionId and not be archived. Required.
adAccountIdstringoptional
New ad account to spend from, if changing it.
namestringoptional
New name for this preset, if changing it.
targetingobjectoptional
All fields are optional. An empty object targets the platform's broadest default audience.
ageMinnumberoptional
Minimum audience age.
ageMaxnumberoptional
Maximum audience age.
gendersarray of numberoptional
Audience genders to target: 1 for male, 2 for female.
geoLocationsobjectoptional
Geographic targeting: countries, regions, cities, and/or zip codes.
countriesarray of stringoptional
regionsarray of objectoptional
keystringoptional
namestringoptional
citiesarray of objectoptional
keystringoptional
namestringoptional
radiusnumberoptional
distanceUnitstringoptional
zipsarray of objectoptional
keystringoptional
namestringoptional
interestsarray of objectoptional
Interest categories to target.
idstringoptional
namestringoptional
publisherPlatformsarray of stringoptional
Which platform surfaces to target, e.g. ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)optional
Restrict the audience to people who like the page (fans) or their friends too (fans_of_fans).
dailyBudgetnumberoptional
New daily budget, in the platform's minor currency unit, if changing it.
durationDaysnumberoptional
New duration in days, if changing it.
delayHoursnumberoptional
New delay in hours before boosting, if changing it.
publisherPlatformsarray of stringoptional
New list of platform surfaces to boost on, if changing it.
Response
dataobjectoptional
boostConfigobjectoptional
idstringoptional
Unique identifier for the boost config.
connectionIdstringoptional
ID of the connected account this boost config belongs to.
adAccountIdstringoptional
ID of the ad account this boost config spends from.
namestringoptional
Name of this preset.
platformstringoptional
Platform this boost config runs on, matching its connected account.
targetingobjectoptional
Targeting settings for this preset.
ageMinnumberoptional
Minimum audience age.
ageMaxnumberoptional
Maximum audience age.
gendersarray of numberoptional
Audience genders to target: 1 for male, 2 for female.
geoLocationsobjectoptional
Geographic targeting: countries, regions, cities, and/or zip codes.
interestsarray of objectoptional
Interest categories to target.
publisherPlatformsarray of stringoptional
Which platform surfaces to target, e.g. ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)optional
Restrict the audience to people who like the page (fans) or their friends too (fans_of_fans).
dailyBudgetnumberoptional
Daily budget, in the platform's minor currency unit (e.g. cents).
durationDaysnumberoptional
How many days the boost runs once applied.
delayHoursnumberoptional
Hours to wait after a post is published before boosting it.
publisherPlatformsarray of stringoptional
Which platform surfaces this preset boosts on.
archivedbooleanoptional
Whether this preset has been archived.
createdAtstringoptional
When this preset was created, as an ISO 8601 timestamp.
updatedAtstringoptional
When this preset was last updated, as an ISO 8601 timestamp.
adAccountobjectoptional
A short summary of the ad account this preset spends from, or null.
platformAccountIdstringoptional
The platform's own identifier for that ad account.
namestringoptional
Display name of that ad account.
currencystringoptional
Currency that ad account bills in, or null.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/boost-configs/update
Your API key
Request body*
{
  "data": {
    "boostConfig": {
      "id": "boost_1",
      "connectionId": "conn_1",
      "adAccountId": "adacct_1",
      "name": "Local awareness — $15/day",
      "platform": "facebook",
      "targeting": {
        "ageMin": 25,
        "ageMax": 55,
        "genders": [],
        "publisherPlatforms": [
          "facebook"
        ]
      },
      "dailyBudget": 15,
      "durationDays": 7,
      "delayHours": 0,
      "publisherPlatforms": [
        "facebook"
      ],
      "archived": false,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-02-01T09:00:00.000Z"
    }
  }
}
v1Resources/Connections/postArchive a boost config

Archives a saved boost configuration so it no longer appears as a reusable preset. Does not affect any boost already in progress that was created from it.

Archive a boost config

post/api/v1/connections/boost-configs/archive
connections:write
Request body
connectionIdstringrequired
The connected account that owns the boost config. Required. Look it up with GET /api/v1/connections.
configIdstringrequired
The boost config to archive. Must belong to connectionId. Required.
Response
dataobjectoptional
archivedbooleanoptional
Always true on success.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/connections/boost-configs/archive
Your API key
Request body*
{
  "data": {
    "archived": true
  }
}
v1Resources/Connections/getList connected apps

Returns the business apps (CRMs and other third-party tools) your agency has connected through Pipedream. These are agency-wide — a key scoped to specific clients still sees the full list, since there is no per-client ownership of an app connection.

List connected apps

get/api/v1/connections/apps
connections:read
Query parameters
appSlugstringoptional
Restrict results to one app, by its slug.
Response
dataobjectoptional
connectionsarray of objectoptional
The business apps connected through Pipedream.
appstringoptional
The app's identifying slug.
appNamestringoptional
Display name of the app.
accountstringoptional
Label of the connected account within that app, or null.
statusstringoptional
Current connection status.
errorstringoptional
The last connection error, or null.
connectedAtstringoptional
When this app was connected, as an ISO 8601 timestamp.
lastCheckedAtstringoptional
When this connection was last health-checked, as an ISO 8601 timestamp, or null.
countnumberoptional
Total number of connected apps matching the request.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/connections/apps
Your API key
appSlug
{
  "data": {
    "connections": [],
    "count": 0
  }
}