Listar marcas | Listings API

Parámetros

Consulta

Nombre	Tipo	Obligatorio	Descripción	Predeterminado
filters	string	opcional	JSON-encoded filter object with two fields. `statuses` (array of strings, required inside the object) selects which brand states to return: `ACTIVE` or `ARCHIVED`. `profileName` (string, optional) is a case-insensitive substring match on the brand name. Omit the parameter entirely to return active brands.	—
page	integer	opcional	1-based page number. Defaults to 1.	—
size	integer	opcional	Rows per page. Defaults to 20.	—

Respuestas

200A page of brands plus `pageInfo` for paging.

Response

{  "data": {    "listSocialProfiles": {      "profiles": [        {          "id": "6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902",          "profileName": "Jenny Home",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": "https://jennyhome.example",          "countryIso": "US",          "bio": "Handmade furniture for real homes.",          "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",          "categories": ["Furniture Store", "Home Goods"],          "brandHashtags": ["jennyhome", "handmadefurniture"],          "competitorHashtags": [],          "connectedChannelCount": 3,          "timezone": {            "label": "(GMT-05:00) Eastern Time",            "tzCode": "America/New_York",            "name": "Eastern Standard Time",            "utc": "-05:00"          },          "contentPreferredLanguage": "en"        },        {          "id": "a90f7c22-5db1-4e83-9f40-2b7c6a1e5d33",          "profileName": "Jenny Home Eastside",          "archived": false,          "logo": null,          "profileLogo": null,          "siteUrl": null,          "countryIso": "US",          "bio": null,          "businessIntent": "general",          "categories": [],          "brandHashtags": [],          "competitorHashtags": [],          "connectedChannelCount": 0,          "timezone": {            "label": "(GMT-06:00) Central Time",            "tzCode": "America/Chicago",            "name": "Central Standard Time",            "utc": "-06:00"          },          "contentPreferredLanguage": "en"        }      ],      "pageInfo": {        "total": 11,        "hasNextPage": true,        "totalEngagementPosts": 0,        "totalPublishedPosts": 0      }    }  }}

401Unauthenticated, missing or invalid API key.

Lista las marcas de tu cuenta, una página a la vez. Cada fila es el mismo objeto de marca que GET /social/brands/{brandId} devuelve para una sola marca, por lo que la lista suele bastar para mostrar un selector de marcas sin una segunda solicitud.

Caso de uso: un selector de marcas en tu propia interfaz. Haz esta llamada una vez cuando el usuario abra tu pantalla de publicación y muestra profileName y logo en cada fila. Una marca cuyo connectedChannelCount sea 0 aún no tiene ninguna cuenta social vinculada y no puede publicar; márcala con una etiqueta y dirige al usuario a un enlace de conexión. Recorre las páginas con page y size mientras pageInfo.hasNextPage sea true.

Caso de uso: conciliación de tus registros. Recorre todas las páginas cada noche y compara id con los identificadores de marca que guardaste al crearlas. Una marca que haya desaparecido de la lista predeterminada se ha archivado; pasa filters={"statuses":["ARCHIVED"]} para verla.

Notas.

id es el UUID sin formato adicional que se utiliza como token de ruta brandId en otras partes de la Social API y como socialProfileId en los cuerpos de las solicitudes.
Los filtros se envían como una única cadena codificada en JSON en el parámetro de consulta filters, no como parámetros separados. Aplica la codificación URL a esa cadena. Si envías filters, debe contener statuses; profileName es opcional y puede acompañarlo.
La paginación se basa en desplazamientos (page / size), no en cursores como en los endpoints Locations y Reviews. pageInfo.total es el número total de marcas que coinciden con los criterios, no el número de marcas de esta página. pageInfo.totalEngagementPosts y totalPublishedPosts son contadores de publicaciones compartidos con la lista de publicaciones y aquí tienen el valor 0.
connectedChannelCount cuenta únicamente las conexiones activas; un canal desconectado deja de contarse de inmediato. Para obtener los canales en sí, llama a GET /social/brands/{brandId}/connections.
timezone.tzCode es el identificador IANA que se utiliza como referencia para determinar la hora de cada programación de esa marca; los otros tres campos de zona horaria son etiquetas de visualización.
No hay un límite de marcas con el que comparar. Los planes de API permiten un número ilimitado de marcas, por lo que la longitud de esta lista es informativa. El número que sí está limitado es el de conexiones: consúltalo en GET /social/limits. Archivar una marca desconecta sus conexiones de inmediato, pero sus plazas siguen contando para el límite de maxConnections hasta que termina el período de facturación, por lo que una marca que haya dejado de aparecer en esta lista puede seguir ocupando plazas hasta la renovación.