Synupv1
Criar chave
v1Recursos/Connections

Connections

Gerencie as contas de publisher e redes sociais conectadas da sua agência, suas contas de anúncios, predefinições de configuração de boost e apps de negócio conectados.

Retorna as contas de publisher/redes sociais conectadas da sua agência (Google, Facebook, Instagram, LinkedIn, TikTok e outras), opcionalmente filtradas por cliente ou plataforma.

Listar contas conectadas

get/api/v1/connections
connections:read
Parâmetros de consulta
clientIdstringopcional
Restringe os resultados a um cliente. Quando sua chave está limitada a clientes específicos, os resultados já são pré-filtrados para esses clientes mesmo que isto seja omitido.
platformstringopcional
Restringe os resultados a uma plataforma, ex.: facebook, google.
credentialsValidbooleanopcional
Restringe a contas cujas credenciais armazenadas estão (true) ou não estão (false) atualmente válidas.
fetchStatusstringopcional
Restringe a contas com este status de busca.
cursorstringopcional
Cursor de paginação da nextCursor de uma resposta anterior.
limitintegeropcional
Máximo de contas a retornar, 1–100. O padrão é 20.
Resposta
dataobjectopcional
accountsarray of objectopcional
As contas conectadas correspondentes.
idstringopcional
Identificador único da conta conectada.
platformstringopcional
A plataforma à qual esta conta se conecta, ex.: google, facebook, instagram.
displayNamestringopcional
Nome de exibição da conta conectada.
providerAccountIdstringopcional
O identificador próprio da plataforma para esta conta.
credentialsValidbooleanopcional
Se as credenciais armazenadas estão atualmente válidas.
fetchStatusstringopcional
Status de busca atual para esta conta, ex.: idle, fetching.
fetchErrorstringopcional
A última mensagem de erro de busca, ou null.
errorTagstringopcional
Um código de erro curto legível por máquina, ou null.
gmbGroupIdsarray of stringopcional
IDs de grupo do Google Business Profile associados a esta conta, se houver.
expiresAtstringopcional
Quando o token de acesso desta conta expira, como timestamp ISO 8601, ou null.
dataAccessExpiresAtstringopcional
Quando a janela de acesso a dados da Meta para esta conta expira, como timestamp ISO 8601, ou null.
channelstringopcional
O canal pelo qual esta conexão foi feita.
clientIdstringopcional
ID do cliente ao qual esta conta pertence, ou null para uma conexão de toda a agência.
synupLocationIdstringopcional
Identificador de local legado. Obsoleto — prefira clientLocationId.
clientLocationIdstringopcional
ID do local ao qual esta conta está vinculada, ou null. Prefira este a synupLocationId.
fetchedListingsCountnumberopcional
Número de listagens que esta conta buscou.
lastFetchedAtstringopcional
Quando esta conta completou sua última busca, como timestamp ISO 8601, ou null.
connectionStatusstring (CONNECTED | MISSING | RENEW | DISCONNECTED | SUSPENDED | SUGGESTED_MATCH)opcional
Saúde geral desta conexão: CONNECTED, MISSING, RENEW, DISCONNECTED, SUSPENDED ou SUGGESTED_MATCH.
createdAtstringopcional
Quando esta conta foi conectada, como timestamp ISO 8601.
updatedAtstringopcional
Quando esta conta foi atualizada por último, como timestamp ISO 8601.
nextCursorstringopcional
Cursor de paginação para a próxima página, ou null quando não há mais resultados.
totalCountnumberopcional
Número total de contas correspondentes à solicitação.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections
Sua chave de API
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
  }
}
v1Recursos/Connections/getObter um resumo de contas conectadas

Quantos locais deste cliente (ou de toda a agência) têm Google/Facebook conectado ou não. Limite o escopo com tags.

Obter um resumo de contas conectadas

get/api/v1/connections/summary
connections:read
Parâmetros de consulta
clientIdstringopcional
Limitar aos locais de um cliente.
tagsstringopcional
Nomes de tags de local separados por vírgula — apenas locais com pelo menos uma dessas tags são contados.
Resposta
dataobjectopcional
totalnumberopcional
Total de locais no escopo.
googleobjectopcional
connectednumberopcional
Locais com este publisher conectado.
notConnectednumberopcional
Locais sem este publisher conectado.
facebookobjectopcional
connectednumberopcional
Locais com este publisher conectado.
notConnectednumberopcional
Locais sem este publisher conectado.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections/summary
Sua chave de API
clientId
tags
{
  "data": {
    "total": 5,
    "google": {
      "connected": 3,
      "notConnected": 2
    },
    "facebook": {
      "connected": 1,
      "notConnected": 4
    }
  }
}
v1Recursos/Connections/getObter uma URL de conexão do Google

Retorna uma URL de autorização OAuth do Google para abrir em um navegador e conectar o Perfil da Empresa no Google deste local. Este endpoint não pode concluir a conexão sozinho — a tela de consentimento do Google requer um humano interativo.

Obter uma URL de conexão do Google

get/api/v1/connections/google/connect-url
connections:write
Parâmetros de consulta
locationIdstringobrigatório
O local a conectar.
clientIdstringopcional
O cliente do local. Necessário apenas para desambiguar quando sua chave é limitada a clientes específicos.
returnUrlstringopcional
Caminho interno do app para onde ir após o humano concluir a tela de consentimento. Padrão: "/".
Resposta
dataobjectopcional
providerstring (google | facebook)opcional
Qual publisher esta URL conecta.
locationIdstringopcional
O local ao qual esta conexão será pareada assim que aprovada.
urlstringopcional
A URL de autorização — abra-a em um navegador sob o controle do proprietário da conta.
notestringopcional
Explica que não há callback para sua integração; consulte GET /api/v1/connections depois.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections/google/connect-url
Sua chave de API
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."
  }
}
v1Recursos/Connections/getObter uma URL de conexão do Facebook

Retorna uma URL de autorização OAuth do Facebook para abrir em um navegador e conectar a Página do Facebook deste local. Este endpoint não pode concluir a conexão sozinho — a tela de consentimento do Facebook requer um humano interativo.

Obter uma URL de conexão do Facebook

get/api/v1/connections/facebook/connect-url
connections:write
Parâmetros de consulta
locationIdstringobrigatório
O local a conectar.
clientIdstringopcional
O cliente do local. Necessário apenas para desambiguar quando sua chave é limitada a clientes específicos.
returnUrlstringopcional
Caminho interno do app para onde ir após o humano concluir a tela de consentimento. Padrão: "/".
Resposta
dataobjectopcional
providerstring (google | facebook)opcional
Qual publisher esta URL conecta.
locationIdstringopcional
O local ao qual esta conexão será pareada assim que aprovada.
urlstringopcional
A URL de autorização — abra-a em um navegador sob o controle do proprietário da conta.
notestringopcional
Explica que não há callback para sua integração; consulte GET /api/v1/connections depois.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections/facebook/connect-url
Sua chave de API
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."
  }
}
v1Recursos/Connections/getListar contas de anúncios

Retorna as contas de anúncios de mídia paga disponíveis em uma conta conectada (Facebook, Instagram, LinkedIn ou TikTok).

Listar contas de anúncios

get/api/v1/connections/ad-accounts
connections:read
Parâmetros de consulta
connectionIdstringobrigatório
A conta conectada a ser consultada. Obrigatório. Procure com GET /api/v1/connections.
Resposta
dataobjectopcional
adAccountsarray of objectopcional
As contas de anúncios disponíveis nesta conta conectada.
idstringopcional
Identificador único da conta de anúncios.
connectionIdstringopcional
ID da conta conectada à qual esta conta de anúncios pertence.
platformAccountIdstringopcional
O identificador próprio da plataforma para esta conta de anúncios, ex.: act_226123609900306 para Meta.
namestringopcional
Nome de exibição da conta de anúncios.
platformstringopcional
Plataforma à qual esta conta de anúncios pertence: facebook, instagram, linkedin ou tiktok.
statusstring (active | disabled | unsettled | pending_review)opcional
Status reportado pela plataforma: active, disabled, unsettled ou pending_review.
isSelectedbooleanopcional
Se esta é a conta de anúncios atualmente selecionada para impulsionar nesta conexão.
currencystringopcional
Moeda em que esta conta de anúncios cobra, ou null.
archivedbooleanopcional
Se esta conta de anúncios foi arquivada.
createdAtstringopcional
Quando esta conta de anúncios foi sincronizada por primeira vez, como timestamp ISO 8601.
updatedAtstringopcional
Quando esta conta de anúncios foi sincronizada por último, como timestamp ISO 8601.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections/ad-accounts
Sua chave de API
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"
      }
    ]
  }
}
v1Recursos/Connections/postSincronizar contas de anúncios

Força uma nova busca imediata das contas de anúncios de uma conta conectada a partir da plataforma, em vez de esperar pela sincronização diária em segundo plano. Retorna a lista atualizada.

Sincronizar contas de anúncios

post/api/v1/connections/ad-accounts/sync
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada a ser sincronizada. Obrigatório. Procure com GET /api/v1/connections.
Resposta
dataobjectopcional
adAccountsarray of objectopcional
As contas de anúncios disponíveis nesta conta conectada.
idstringopcional
Identificador único da conta de anúncios.
connectionIdstringopcional
ID da conta conectada à qual esta conta de anúncios pertence.
platformAccountIdstringopcional
O identificador próprio da plataforma para esta conta de anúncios, ex.: act_226123609900306 para Meta.
namestringopcional
Nome de exibição da conta de anúncios.
platformstringopcional
Plataforma à qual esta conta de anúncios pertence: facebook, instagram, linkedin ou tiktok.
statusstring (active | disabled | unsettled | pending_review)opcional
Status reportado pela plataforma: active, disabled, unsettled ou pending_review.
isSelectedbooleanopcional
Se esta é a conta de anúncios atualmente selecionada para impulsionar nesta conexão.
currencystringopcional
Moeda em que esta conta de anúncios cobra, ou null.
archivedbooleanopcional
Se esta conta de anúncios foi arquivada.
createdAtstringopcional
Quando esta conta de anúncios foi sincronizada por primeira vez, como timestamp ISO 8601.
updatedAtstringopcional
Quando esta conta de anúncios foi sincronizada por último, como timestamp ISO 8601.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
422Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/ad-accounts/sync
Sua chave de API
Corpo da solicitação*
{
  "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"
      }
    ]
  }
}
v1Recursos/Connections/postSelecionar uma conta de anúncios

Escolhe qual das contas de anúncios de uma conta conectada é usada ao impulsionar publicações. Apenas uma conta de anúncios pode ser selecionada por conta conectada por vez.

Selecionar uma conta de anúncios

post/api/v1/connections/ad-accounts/select
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada proprietária da conta de anúncios. Obrigatório. Procure com GET /api/v1/connections.
adAccountIdstringobrigatório
A conta de anúncios a ser selecionada. Deve pertencer a connectionId. Obrigatório.
Resposta
dataobjectopcional
selectedbooleanopcional
Sempre true em caso de sucesso.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/ad-accounts/select
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "selected": true
  }
}
v1Recursos/Connections/postAtribuir uma listagem a um local

Vincula uma listagem já obtida de uma conta já conectada a um local que ainda não tem conexão própria. Não é uma nova concessão OAuth — caId já deve ser uma conta conectada; isso apenas reaproveita esse login. Somente Google e Facebook.

Atribuir uma listagem a um local

post/api/v1/connections/locations/assign
connections:write
Corpo da solicitação
platformstring (google | facebook)obrigatório
A plataforma: google ou facebook. Obrigatório.
caIdstringobrigatório
A conta já conectada a vincular. Obrigatório.
locationIdstringobrigatório
O local ao qual atribuir esta listagem. Obrigatório.
platformResourceNamestringobrigatório
O nome/id de recurso da listagem na plataforma. Obrigatório.
platformPageNamestringobrigatório
O nome de exibição da listagem na plataforma. Obrigatório.
Resposta
dataobjectopcional
idstringopcional
Identificador único da conexão resultante.
platformstring (google | facebook)opcional
A plataforma na qual a listagem foi vinculada.
synupLocationIdstringopcional
O id legado do Synup do local, ou null para um local nativo.
clientLocationIdstringopcional
O id do local.
platformResourceNamestringopcional
O nome/id de recurso da listagem na plataforma.
platformPageNamestringopcional
O nome de exibição da listagem na plataforma.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/locations/assign
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "id": "listing_1",
    "platform": "google",
    "synupLocationId": null,
    "clientLocationId": "loc_456",
    "platformResourceName": "accounts/123/locations/456",
    "platformPageName": "Acme Dental — Downtown"
  }
}
v1Recursos/Connections/postConfirmar uma correspondência sugerida

Confirma uma sugestão da pontuação NAP, criando uma conexão em nível de local a partir de uma listagem obtida já correspondida a um local do Synup. Falha se a listagem não tiver local correspondido (400), já estiver conectada (409), ou o local já tiver uma conexão nessa plataforma (409).

Confirmar uma correspondência sugerida

post/api/v1/connections/locations/confirm-match
connections:write
Corpo da solicitação
fetchedListingIdstringobrigatório
A listagem obtida a confirmar. Obrigatório.
Resposta
dataobjectopcional
idstringopcional
Identificador único da conexão resultante.
platformstring (google | facebook)opcional
A plataforma na qual a listagem foi vinculada.
synupLocationIdstringopcional
O id legado do Synup do local, ou null para um local nativo.
clientLocationIdstringopcional
O id do local.
platformResourceNamestringopcional
O nome/id de recurso da listagem na plataforma.
platformPageNamestringopcional
O nome de exibição da listagem na plataforma.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
409A solicitação entra em conflito com o estado atual do recurso — por exemplo, alterar o e-mail ou telefone de um destinatário que já recebeu uma mensagem, ou um convite de equipe que já foi aceito (ou que ainda não foi aceito).
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/locations/confirm-match
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "id": "listing_1",
    "platform": "google",
    "synupLocationId": null,
    "clientLocationId": "loc_456",
    "platformResourceName": "accounts/123/locations/456",
    "platformPageName": "Acme Dental — Downtown"
  }
}
v1Recursos/Connections/postSolicitar novas sugestões de correspondência

Executa novamente a pontuação NAP (nome/endereço/telefone) sobre as listagens já obtidas de uma conta conectada. Não busca novamente na plataforma — use POST /api/v1/connections/fetch-listings para isso. Limitado a uma vez a cada 24 horas por conta; uma chamada dentro dessa janela retorna 429 com um timestamp retryAt.

Solicitar novas sugestões de correspondência

post/api/v1/connections/request-matches
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada a pontuar novamente. Obrigatório. Procure com GET /api/v1/connections.
Resposta
dataobjectopcional
scorednumberopcional
Número de listagens pontuadas novamente.
messagestringopcional
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/request-matches
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "scored": 4,
    "message": null
  }
}
v1Recursos/Connections/postForçar nova busca das listagens de uma conta

Força uma nova busca imediata das listagens de uma conta conectada diretamente na plataforma — não apenas uma nova pontuação do que já está armazenado, que é POST /api/v1/connections/request-matches. Executa de forma síncrona; a resposta confirma que a busca já foi concluída.

Forçar nova busca das listagens de uma conta

post/api/v1/connections/fetch-listings
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada a buscar novamente. Obrigatório. Procure com GET /api/v1/connections.
Resposta
dataobjectopcional
statusstringopcional
countnumberopcional
Número de listagens buscadas.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/fetch-listings
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "status": "completed",
    "count": 4
  }
}
v1Recursos/Connections/getListar configurações de boost

Retorna as configurações de boost salvas (predefinições reutilizáveis de segmentação e orçamento para impulsionar uma publicação) em uma conta conectada.

Listar configurações de boost

get/api/v1/connections/boost-configs
connections:read
Parâmetros de consulta
connectionIdstringobrigatório
A conta conectada a ser consultada. Obrigatório. Procure com GET /api/v1/connections.
Resposta
dataobjectopcional
boostConfigsarray of objectopcional
As configurações de boost salvas nesta conta conectada.
idstringopcional
Identificador único da configuração de boost.
connectionIdstringopcional
ID da conta conectada à qual esta configuração de boost pertence.
adAccountIdstringopcional
ID da conta de anúncios da qual esta configuração de boost gasta.
namestringopcional
Nome desta predefinição.
platformstringopcional
Plataforma em que esta configuração de boost é executada, correspondendo à sua conta conectada.
targetingobjectopcional
Configurações de segmentação para esta predefinição.
ageMinnumberopcional
Idade mínima do público.
ageMaxnumberopcional
Idade máxima do público.
gendersarray of numberopcional
Gêneros do público a segmentar: 1 para masculino, 2 para feminino.
geoLocationsobjectopcional
Segmentação geográfica: países, regiões, cidades e/ou códigos postais.
interestsarray of objectopcional
Categorias de interesse a segmentar.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma segmentar, ex.: ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)opcional
Restringe o público a pessoas que curtem a página (fans) ou também aos amigos delas (fans_of_fans).
dailyBudgetnumberopcional
Orçamento diário, na unidade monetária menor da plataforma (ex.: centavos).
durationDaysnumberopcional
Quantos dias o boost dura quando aplicado.
delayHoursnumberopcional
Horas a esperar após a publicação de um post antes de impulsioná-lo.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma esta predefinição impulsiona.
archivedbooleanopcional
Se esta predefinição foi arquivada.
createdAtstringopcional
Quando esta predefinição foi criada, como timestamp ISO 8601.
updatedAtstringopcional
Quando esta predefinição foi atualizada por último, como timestamp ISO 8601.
adAccountobjectopcional
Um breve resumo da conta de anúncios da qual esta predefinição gasta, ou null.
platformAccountIdstringopcional
O identificador próprio da plataforma para essa conta de anúncios.
namestringopcional
Nome de exibição dessa conta de anúncios.
currencystringopcional
Moeda em que essa conta de anúncios cobra, ou null.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections/boost-configs
Sua chave de API
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"
      }
    ]
  }
}
v1Recursos/Connections/postCriar uma configuração de boost

Salva uma nova configuração de boost reutilizável (segmentação, orçamento diário e duração) na conta de anúncios de uma conta conectada. Isso apenas armazena uma predefinição para uso posterior — não impulsiona uma publicação, não envia nada à plataforma de anúncios, e não gasta dinheiro algum. Dinheiro só é gasto quando esta configuração salva é posteriormente aplicada para impulsionar uma publicação específica.

Criar uma configuração de boost

post/api/v1/connections/boost-configs
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada à qual vincular esta configuração de boost. Obrigatório. Procure com GET /api/v1/connections.
adAccountIdstringobrigatório
A conta de anúncios da qual gastar quando esta configuração for usada. Deve pertencer a connectionId. Obrigatório.
namestringobrigatório
Um nome para esta predefinição, exibido ao selecioná-la posteriormente. Obrigatório.
targetingobjectopcional
Todos os campos são opcionais. Um objeto vazio segmenta o público padrão mais amplo da plataforma.
ageMinnumberopcional
Idade mínima do público.
ageMaxnumberopcional
Idade máxima do público.
gendersarray of numberopcional
Gêneros do público a segmentar: 1 para masculino, 2 para feminino.
geoLocationsobjectopcional
Segmentação geográfica: países, regiões, cidades e/ou códigos postais.
countriesarray of stringopcional
regionsarray of objectopcional
keystringopcional
namestringopcional
citiesarray of objectopcional
keystringopcional
namestringopcional
radiusnumberopcional
distanceUnitstringopcional
zipsarray of objectopcional
keystringopcional
namestringopcional
interestsarray of objectopcional
Categorias de interesse a segmentar.
idstringopcional
namestringopcional
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma segmentar, ex.: ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)opcional
Restringe o público a pessoas que curtem a página (fans) ou também aos amigos delas (fans_of_fans).
dailyBudgetnumberobrigatório
Orçamento diário, na unidade monetária menor da plataforma (ex.: centavos). Deve ser positivo. Obrigatório.
durationDaysnumberobrigatório
Quantos dias o boost deve durar quando aplicado. Deve ser positivo. Obrigatório.
delayHoursnumberopcional
Horas a esperar após a publicação de um post antes de impulsioná-lo. O padrão é 0.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma impulsionar, ex.: ["facebook", "instagram"].
Resposta
dataobjectopcional
boostConfigobjectopcional
idstringopcional
Identificador único da configuração de boost.
connectionIdstringopcional
ID da conta conectada à qual esta configuração de boost pertence.
adAccountIdstringopcional
ID da conta de anúncios da qual esta configuração de boost gasta.
namestringopcional
Nome desta predefinição.
platformstringopcional
Plataforma em que esta configuração de boost é executada, correspondendo à sua conta conectada.
targetingobjectopcional
Configurações de segmentação para esta predefinição.
ageMinnumberopcional
Idade mínima do público.
ageMaxnumberopcional
Idade máxima do público.
gendersarray of numberopcional
Gêneros do público a segmentar: 1 para masculino, 2 para feminino.
geoLocationsobjectopcional
Segmentação geográfica: países, regiões, cidades e/ou códigos postais.
interestsarray of objectopcional
Categorias de interesse a segmentar.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma segmentar, ex.: ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)opcional
Restringe o público a pessoas que curtem a página (fans) ou também aos amigos delas (fans_of_fans).
dailyBudgetnumberopcional
Orçamento diário, na unidade monetária menor da plataforma (ex.: centavos).
durationDaysnumberopcional
Quantos dias o boost dura quando aplicado.
delayHoursnumberopcional
Horas a esperar após a publicação de um post antes de impulsioná-lo.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma esta predefinição impulsiona.
archivedbooleanopcional
Se esta predefinição foi arquivada.
createdAtstringopcional
Quando esta predefinição foi criada, como timestamp ISO 8601.
updatedAtstringopcional
Quando esta predefinição foi atualizada por último, como timestamp ISO 8601.
adAccountobjectopcional
Um breve resumo da conta de anúncios da qual esta predefinição gasta, ou null.
platformAccountIdstringopcional
O identificador próprio da plataforma para essa conta de anúncios.
namestringopcional
Nome de exibição dessa conta de anúncios.
currencystringopcional
Moeda em que essa conta de anúncios cobra, ou null.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/boost-configs
Sua chave de API
Corpo da solicitação*
{
  "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"
    }
  }
}
v1Recursos/Connections/postAtualizar uma configuração de boost

Edita uma configuração de boost existente e não arquivada. Somente os campos fornecidos são alterados.

Atualizar uma configuração de boost

post/api/v1/connections/boost-configs/update
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada proprietária da configuração de boost. Obrigatório. Procure com GET /api/v1/connections.
configIdstringobrigatório
A configuração de boost a ser atualizada. Deve pertencer a connectionId e não estar arquivada. Obrigatório.
adAccountIdstringopcional
Nova conta de anúncios da qual gastar, se estiver alterando.
namestringopcional
Novo nome para esta predefinição, se estiver alterando.
targetingobjectopcional
Todos os campos são opcionais. Um objeto vazio segmenta o público padrão mais amplo da plataforma.
ageMinnumberopcional
Idade mínima do público.
ageMaxnumberopcional
Idade máxima do público.
gendersarray of numberopcional
Gêneros do público a segmentar: 1 para masculino, 2 para feminino.
geoLocationsobjectopcional
Segmentação geográfica: países, regiões, cidades e/ou códigos postais.
countriesarray of stringopcional
regionsarray of objectopcional
keystringopcional
namestringopcional
citiesarray of objectopcional
keystringopcional
namestringopcional
radiusnumberopcional
distanceUnitstringopcional
zipsarray of objectopcional
keystringopcional
namestringopcional
interestsarray of objectopcional
Categorias de interesse a segmentar.
idstringopcional
namestringopcional
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma segmentar, ex.: ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)opcional
Restringe o público a pessoas que curtem a página (fans) ou também aos amigos delas (fans_of_fans).
dailyBudgetnumberopcional
Novo orçamento diário, na unidade monetária menor da plataforma, se estiver alterando.
durationDaysnumberopcional
Nova duração em dias, se estiver alterando.
delayHoursnumberopcional
Novo atraso em horas antes de impulsionar, se estiver alterando.
publisherPlatformsarray of stringopcional
Nova lista de superfícies de plataforma para impulsionar, se estiver alterando.
Resposta
dataobjectopcional
boostConfigobjectopcional
idstringopcional
Identificador único da configuração de boost.
connectionIdstringopcional
ID da conta conectada à qual esta configuração de boost pertence.
adAccountIdstringopcional
ID da conta de anúncios da qual esta configuração de boost gasta.
namestringopcional
Nome desta predefinição.
platformstringopcional
Plataforma em que esta configuração de boost é executada, correspondendo à sua conta conectada.
targetingobjectopcional
Configurações de segmentação para esta predefinição.
ageMinnumberopcional
Idade mínima do público.
ageMaxnumberopcional
Idade máxima do público.
gendersarray of numberopcional
Gêneros do público a segmentar: 1 para masculino, 2 para feminino.
geoLocationsobjectopcional
Segmentação geográfica: países, regiões, cidades e/ou códigos postais.
interestsarray of objectopcional
Categorias de interesse a segmentar.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma segmentar, ex.: ["facebook", "instagram"].
pageFansstring (fans | fans_of_fans)opcional
Restringe o público a pessoas que curtem a página (fans) ou também aos amigos delas (fans_of_fans).
dailyBudgetnumberopcional
Orçamento diário, na unidade monetária menor da plataforma (ex.: centavos).
durationDaysnumberopcional
Quantos dias o boost dura quando aplicado.
delayHoursnumberopcional
Horas a esperar após a publicação de um post antes de impulsioná-lo.
publisherPlatformsarray of stringopcional
Em quais superfícies de plataforma esta predefinição impulsiona.
archivedbooleanopcional
Se esta predefinição foi arquivada.
createdAtstringopcional
Quando esta predefinição foi criada, como timestamp ISO 8601.
updatedAtstringopcional
Quando esta predefinição foi atualizada por último, como timestamp ISO 8601.
adAccountobjectopcional
Um breve resumo da conta de anúncios da qual esta predefinição gasta, ou null.
platformAccountIdstringopcional
O identificador próprio da plataforma para essa conta de anúncios.
namestringopcional
Nome de exibição dessa conta de anúncios.
currencystringopcional
Moeda em que essa conta de anúncios cobra, ou null.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/boost-configs/update
Sua chave de API
Corpo da solicitação*
{
  "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"
    }
  }
}
v1Recursos/Connections/postArquivar uma configuração de boost

Arquiva uma configuração de boost salva para que não apareça mais como uma predefinição reutilizável. Não afeta nenhum boost já em andamento criado a partir dela.

Arquivar uma configuração de boost

post/api/v1/connections/boost-configs/archive
connections:write
Corpo da solicitação
connectionIdstringobrigatório
A conta conectada proprietária da configuração de boost. Obrigatório. Procure com GET /api/v1/connections.
configIdstringobrigatório
A configuração de boost a ser arquivada. Deve pertencer a connectionId. Obrigatório.
Resposta
dataobjectopcional
archivedbooleanopcional
Sempre true em caso de sucesso.
Erros
400Falta um parâmetro obrigatório na solicitação, ou ela é inválida de outra forma.
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
404O recurso não foi encontrado, ou não pertence à sua agência.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
post/api/v1/connections/boost-configs/archive
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "archived": true
  }
}
v1Recursos/Connections/getListar apps conectados

Retorna os apps de negócio (CRMs e outras ferramentas de terceiros) que sua agência conectou através do Pipedream. Estes são de toda a agência — uma chave limitada a clientes específicos ainda vê a lista completa, já que não há propriedade por cliente de uma conexão de app.

Listar apps conectados

get/api/v1/connections/apps
connections:read
Parâmetros de consulta
appSlugstringopcional
Restringe os resultados a um app, pelo seu slug.
Resposta
dataobjectopcional
connectionsarray of objectopcional
Os apps de negócio conectados através do Pipedream.
appstringopcional
O slug identificador do app.
appNamestringopcional
Nome de exibição do app.
accountstringopcional
Rótulo da conta conectada dentro desse app, ou null.
statusstringopcional
Status de conexão atual.
errorstringopcional
O último erro de conexão, ou null.
connectedAtstringopcional
Quando este app foi conectado, como timestamp ISO 8601.
lastCheckedAtstringopcional
Quando esta conexão foi verificada por último, como timestamp ISO 8601, ou null.
countnumberopcional
Número total de apps conectados correspondentes à solicitação.
Erros
401Chave de API ausente, inválida, expirada ou revogada.
403A chave não tem a permissão exigida, ou não está autorizada para este cliente/local.
429Muitas solicitações. Tente novamente após o número de segundos indicado no cabeçalho Retry-After.
get/api/v1/connections/apps
Sua chave de API
appSlug
{
  "data": {
    "connections": [],
    "count": 0
  }
}