Listings APIListings API
로그인
POST/api/v4/social/brands

브랜드 생성

연결된 소셜 계정과 해당 계정에서 발행한 게시물을 소유하는 컨테이너인 소셜 브랜드를 생성합니다. API 요금제에서는 브랜드 수에 제한이 없습니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

본문

이름유형필수설명
inputobject필수Wrapper object. Every field below is a property of `input`, the entire body must be nested under it.
input.profileNamestring필수Display name of the brand. Shown wherever the brand is listed and used as the default author name in the composer.
input.timezoneobject필수The 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.businessIntentstring선택One or two sentences describing what the business does, used to tailor content suggestions. Defaults to `general` when omitted.
input.categoriesarray of strings선택Business categories for the brand, e.g. `["Furniture Store"]`. Defaults to an empty list.
input.siteUrlstring선택The brand's website. Used to enrich content suggestions; setting it also queues a one-off read of the site.
input.logostring선택Public https URL of the brand logo.
input.countryIsostring선택Two-letter ISO country code for the brand, e.g. `US`.
input.biostring선택Short brand bio.
input.brandHashtagsarray of strings선택Hashtags that belong to the brand, offered as suggestions in the composer.
input.competitorHashtagsarray of strings선택Competitor hashtags to track alongside the brand's own.
input.contentPreferredLanguagestring선택Preferred language for generated content, e.g. `en`.

요청 예시

바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.

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"]  }}

응답

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.

Social API의 최상위 객체인 브랜드를 생성합니다. 브랜드는 연결한 소셜 계정과 해당 계정에서 발행한 모든 게시물을 소유합니다. 브랜드가 하나 이상 존재하기 전에는 Social API의 다른 기능을 호출할 수 없으므로, 모든 Social 연동에서 이 요청을 가장 먼저 보냅니다.

사용 사례: 고객의 소셜 게시 기능 온보딩. 고객이 제품에 가입하면 게시물을 발행하려는 비즈니스마다 브랜드를 하나씩 생성합니다. 반환된 socialProfile.id를 해당 비즈니스의 자체 레코드에 저장합니다. 이 값은 POST /social/brands/{brandId}/connections/link 및 GET /social/brands/{brandId}/posts의 brandId 경로 토큰이며, 생성하는 모든 게시물의 socialProfileId 본문 필드입니다. 그런 다음 사용자가 게시물을 발행하려는 각 플랫폼의 호스팅된 연결 링크를 통해 연결을 진행하도록 안내합니다.

참고 사항.

  • 요청 본문은 반드시 input 객체로 감싸야 합니다. Social API의 모든 쓰기 요청은 이 방식으로 감싸지만, 연결 링크는 예외적으로 평면 구조의 본문을 받습니다.
  • HTTP 상태가 아니라 success를 확인합니다. profileName 누락이나 알 수 없는 timezone.tzCode로 인한 유효성 검사 실패 시, success: false와 error에 담긴 사유를 포함한 HTTP 200이 반환됩니다. success가 true인 경우에만 호출이 성공한 것으로 처리합니다.
  • profileName과 timezone만 필수입니다. businessIntent와 categories의 기본값은 각각 general과 빈 목록이므로, 연동 시스템에 이에 해당하는 필드가 없다면 완전히 생략할 수 있습니다.
  • timezone.tzCode는 실제 예약 시간에 영향을 줍니다. scheduleDate + scheduleTime으로 예약한 게시물은 호출자의 시간대나 UTC가 아닌 브랜드의 시간대를 기준으로 해석됩니다. 나중에 이 값을 변경해도 이미 예약된 게시물의 시간은 변경되지 않습니다.
  • 브랜드는 항상 API 키에 연결된 계정에 속합니다. 다른 계정에 브랜드를 생성할 수는 없으며, 본문에 포함된 계정 식별자는 모두 무시됩니다.
  • 브랜드 ID는 일반 UUID입니다. Locations 및 사업장 Posts에서 사용하는 Base64 릴레이 ID가 아니므로 인코딩하거나 디코딩하지 않습니다. 동일한 ID가 brandId 경로 토큰과 socialProfileId 본문 필드에 사용되며, brandId는 URL 토큰으로만 사용되고 본문 필드로는 절대 사용되지 않습니다.
  • API 요금제에는 브랜드 수 제한이 없습니다. 브랜드 수는 무제한이며 사용량으로 집계되지 않으므로, 이 호출은 한도 때문에 거부되지 않으며 생성 전에 남은 용량을 확인할 필요도 없습니다. 사용량으로 집계되는 것은 연결이며, 하나의 네트워크에서 소셜 계정 하나를 브랜드 하나에 연결하면 연결 1개로 계산됩니다. 연결 수에 따른 등급과 연결 팩 가격은 요금제 및 추가 기능을 참조하고, 사용자에게 연결 링크를 안내하기 전에 남은 연결 용량을 확인하려면 GET /social/limits를 참조합니다.

쓰기 작업: 실제 계정에서는 실행하지 않았습니다. 표시된 요청과 응답은 API 스키마를 바탕으로 작성되었습니다.

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