Listings APIListings API
Anmelden
POST/api/v4/social/brands

Marke erstellen

Erstellt eine Social-Media-Marke als Container für verbundene Konten und deren veröffentlichte Beiträge. API-Tarife erlauben unbegrenzt viele Marken.

Erfordert einen API-Schlüssel. Format des Headers und Schlüsselrotation finden Sie unter Authentifizierung.

Parameter

Body

NameTypErforderlichBeschreibung
inputobjecterforderlichWrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.profileNamestringerforderlichDisplay name of the brand. Shown wherever the brand is listed and used as the default author name in the composer.
input.timezoneobjecterforderlichThe brand's timezone as `{ label, tzCode, name, utc }`, all strings. `tzCode` is the one that matters: it is the IANA identifier the API validates and uses to interpret every `scheduleDate` / `scheduleTime` on this brand's posts. The other three are display labels.
input.businessIntentstringoptionalOne or two sentences describing what the business does, used to tailor content suggestions. Defaults to `general` when omitted.
input.categoriesarray of stringsoptionalBusiness categories for the brand, e.g. `["Furniture Store"]`. Defaults to an empty list.
input.siteUrlstringoptionalThe brand's website. Used to enrich content suggestions; setting it also queues a one-off read of the site.
input.logostringoptionalPublic https URL of the brand logo.
input.countryIsostringoptionalTwo-letter ISO country code for the brand, e.g. `US`.
input.biostringoptionalShort brand bio.
input.brandHashtagsarray of stringsoptionalHashtags that belong to the brand, offered as suggestions in the composer.
input.competitorHashtagsarray of stringsoptionalCompetitor hashtags to track alongside the brand's own.
input.contentPreferredLanguagestringoptionalPreferred language for generated content, e.g. `en`.

Beispielanfrage

Body zum direkten Einfügen. Ersetzen Sie Platzhalter-IDs und -Werte durch Ihre eigenen.

Request body
{  "input": {    "profileName": "Jenny Home",    "timezone": {      "label": "(GMT-05:00) Eastern Time",      "tzCode": "America/New_York",      "name": "Eastern Standard Time",      "utc": "-05:00"    },    "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",    "categories": ["Furniture Store", "Home Goods"],    "siteUrl": "https://jennyhome.example",    "countryIso": "US",    "bio": "Handmade furniture for real homes.",    "brandHashtags": ["jennyhome", "handmadefurniture"]  }}

Antworten

200Brand created. `socialProfile.id` is the `brandId` every other Social endpoint takes.
Response
{  "data": {    "createSocialProfile": {      "success": true,      "error": null,      "socialProfile": {        "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": 0,        "timezone": {          "label": "(GMT-05:00) Eastern Time",          "tzCode": "America/New_York",          "name": "Eastern Standard Time",          "utc": "-05:00"        },        "contentPreferredLanguage": "en"      }    }  }}
200Validation failed. The status is still 200: read `success`.
Response
{  "data": {    "createSocialProfile": {      "success": false,      "error": {        "message": "SY90003: timezone.tzCode is not a valid IANA identifier",        "code": "SY90003",        "contextInfo": null      },      "socialProfile": null    }  }}
401Unauthenticated, missing or invalid API key.

Erstellt eine Marke: das Objekt auf oberster Ebene in der Social API. Einer Marke sind die Social-Media-Konten, die Sie mit ihr verbinden, und alle darüber veröffentlichten Beiträge zugeordnet. Alle anderen Aufrufe der Social API setzen voraus, dass mindestens eine Marke existiert. Daher ist dies die erste Anfrage in jeder Social-Integration.

Anwendungsfall: einen Kunden für die Veröffentlichung in sozialen Medien einrichten. Wenn sich ein Kunde in Ihrem Produkt registriert, erstellen Sie für jedes Unternehmen, für das er Beiträge veröffentlichen möchte, eine Marke. Speichern Sie die zurückgegebene socialProfile.id in Ihrem eigenen Datensatz für dieses Unternehmen: Sie ist der Pfadparameter brandId in POST /social/brands/{brandId}/connections/link und GET /social/brands/{brandId}/posts sowie das Feld socialProfileId im Anfragetext für jeden Beitrag, den Sie erstellen. Leiten Sie den Nutzer anschließend für jede Plattform, auf der er veröffentlichen möchte, über den gehosteten Verbindungslink weiter.

Hinweise.

  • Der Anfragetext muss in ein input-Objekt eingebettet sein. Jeder Schreibvorgang in der Social API verwendet diese Einbettung, mit einer Ausnahme: Der Verbindungslink erwartet einen flachen Anfragetext.
  • Prüfen Sie success, nicht den HTTP-Status. Ein Validierungsfehler – ein fehlendes profileName oder ein unbekanntes timezone.tzCode – wird als HTTP 200 mit success: false und der Ursache in error zurückgegeben. Betrachten Sie den Aufruf nur dann als erfolgreich, wenn success den Wert true hat.
  • Nur profileName und timezone sind erforderlich. Die Standardwerte für businessIntent und categories sind general beziehungsweise eine leere Liste, sodass eine Integration ohne Entsprechungen für diese Felder sie vollständig weglassen kann.
  • timezone.tzCode ist keine Dekoration. Ein mit scheduleDate + scheduleTime geplanter Beitrag wird in der Zeitzone der Marke interpretiert, nicht in der des Aufrufers und nicht in UTC. Eine spätere Änderung dieser Zeitzone ändert die Veröffentlichungszeitpunkte bereits geplanter Beiträge nicht.
  • Die Marke gehört immer zu dem Konto, dem der API-Schlüssel zugeordnet ist. Es gibt keine Möglichkeit, eine Marke in einem anderen Konto zu erstellen: Jede Kontokennung im Anfragetext wird ignoriert.
  • Marken-IDs sind einfache UUIDs. Sie sind nicht die Base64-Relay-IDs, die von Locations und standortbezogenen Posts verwendet werden. Daher dürfen Sie sie weder kodieren noch dekodieren. Dieselbe ID wird als Pfadparameter brandId und als Feld socialProfileId im Anfragetext verwendet: brandId ist immer nur ein URL-Parameter, niemals ein Feld im Anfragetext.
  • In einem API-Tarif gibt es keine Begrenzung der Markenanzahl. Die Anzahl der Marken ist unbegrenzt und wird nicht als Verbrauch erfasst, sodass dieser Aufruf niemals aufgrund einer Obergrenze abgelehnt wird und Sie vor dem Erstellen einer Marke keine verbleibende Kapazität prüfen müssen. Erfasst werden Verbindungen – jeweils ein Social-Media-Konto, das in einem Netzwerk mit einer Marke verknüpft ist. Unter Tarife und Zusatzpakete finden Sie die Verbindungsstaffeln und den Preis eines Verbindungspakets. Unter GET /social/limits können Sie Ihre verbleibende Verbindungskapazität abrufen, bevor Sie einen Nutzer über einen Verbindungslink weiterleiten.

Schreibvorgang: nicht im Live-Konto ausgeführt. Die gezeigte Anfrage und Antwort wurden anhand des API-Schemas erstellt.

Request
curl -X POST 'https://listingsapi.com/api/v4/social/brands' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "profileName": "Jenny Home",      "timezone": {        "label": "(GMT-05:00) Eastern Time",        "tzCode": "America/New_York",        "name": "Eastern Standard Time",        "utc": "-05:00"      },      "businessIntent": "A family-run home furnishings store selling handmade furniture and textiles.",      "categories": [        "Furniture Store",        "Home Goods"      ],      "siteUrl": "https://jennyhome.example",      "countryIso": "US",      "bio": "Handmade furniture for real homes.",      "brandHashtags": [        "jennyhome",        "handmadefurniture"      ]    }  }'
Run in playground