Provision brands and agents via the API

Overview

A brand represents your legal business entity. An agent is the verified RCS sender tied to that brand. Before an agent can send messages to real users, both must be reviewed and approved by carriers.

When you submit your brand and agent details, Vibes reviews them first. Once approved internally, Vibes routes the details to the appropriate parties on your behalf — brand and agent basics go to Aegis Mobile for identity vetting, and campaign and testing details go to carriers and Google for content and compliance review.

To provision a brand and agent via the API, you follow the same two-operation flow for each resource:

1. PATCH the brand or agent to set the required details
2. POST to .../submit to lock and submit those details for review

You can run PATCH requests at any time and build up the data incrementally. Submitting is what triggers the review process.

Order of operations

The diagram below shows the full flow — who acts at each step, and what conditions must be met before you can proceed.

flowchart TD
    classDef you fill:#dbeafe,stroke:#3b82f6,color:#1d4ed8
    classDef vibes fill:#fef3c7,stroke:#d97706,color:#92400e
    classDef ext fill:#d1fae5,stroke:#059669,color:#065f46
    classDef gate fill:#f3f4f6,stroke:#6b7280,color:#111827

    PB["Step 1 — PATCH /brands/:brandId<br/>Set brand details"]:::you
    SB["Step 2 — POST /brands/:brandId/submit"]:::you
    VB["Vibes reviews brand"]:::vibes

    PA["Step 3 — PATCH /agents/:agentId<br/>Set agent basics, campaign & testing"]:::you

    S1["Step 4 — submit type: 'basics'"]:::you
    S2["submit type: 'campaign'"]:::you
    S3["submit type: 'testing'"]:::you

    V1["Vibes reviews<br/>brand + agent basics"]:::vibes
    AE["Aegis Mobile<br/>Brand + agent basics vetting"]:::ext

    V2["Vibes reviews<br/>campaign + testing"]:::vibes
    CR["Carriers + Google<br/>Content & compliance review"]:::ext

    LIVE[["🎉  Agent Live"]]:::gate

    PB --> SB --> VB
    VB -- "✓ Brand approved by Vibes" --> S1
    VB -. "changes requested" .-> PB

    PA --> S1
    S1 --> S2 --> S3

    S1 --> V1 --> AE
    S2 --> V2
    S3 --> V2
    V2 --> CR

    AE & CR --> LIVE

Key conditions:

• You can PATCH brand and agent details at any time and submit each section as soon as it's ready — you don't need to wait for Aegis Mobile, carrier, or Google approvals before submitting the next section. The one hard prerequisite is that the brand must have been submitted (i.e. POST /brands/:brandId/submit must have been called) before any agent submit call is accepted — the brand does not need to be fully approved first.
• The lifecycle always progresses in the same fixed order regardless of when you submit: Vibes reviews internally first, then routes brand and agent basics to Aegis Mobile for identity vetting, then routes campaign and testing to carriers and Google for content review. Vibes manages all handoffs — you submit, and the status updates will always follow that sequence.
• Aegis vetting is triggered after Vibes reviews the agent basics submission — at that point Vibes submits both the brand and agent basics to Aegis together
• Brand is submitted and approved once — additional agents under the same brand skip steps 1–2

If changes are requested or a submission is rejected: PATCH the brand or agent with the corrected details, then call the relevant submit endpoint again. Vibes will notify you by email when action is needed.

Step 1 — Patch brand details

PATCH https://api.rcsstudio.ai/brands/{brandId}
Authorization: Bearer <access_token>
Content-Type: application/json

Brand details are submitted to Vibes and forwarded to Aegis Mobile for vetting. Every field must match your official business records.

{
  "legalName": "Acme Corp LLC",
  "legalEntityType": "LIMITED_LIABILITY_COMPANY",
  "organizationType": "PRIVATE_PROFIT",
  "identifiers": [
    { "type": "EIN", "value": "123456789" }
  ],
  "addresses": [
    {
      "line1": "123 Main St",
      "city": "Chicago",
      "state": "IL",
      "postalCode": "60601",
      "country": "US"
    }
  ],
  "websites": [
    { "url": "https://www.acmecorp.com" }
  ],
  "contacts": [
    {
      "type": "BRAND",
      "firstName": "Jane",
      "lastName": "Smith",
      "title": "VP of Marketing",
      "phone": "+12125551234",
      "email": "[email protected]"
    }
  ]
}

Step 2 — Submit brand

POST https://api.rcsstudio.ai/brands/{brandId}/submit
Authorization: Bearer <access_token>

No request body. This submits the brand for Vibes' internal review and unlocks agent submit calls — you do not need to wait for brand approval before proceeding to Step 3. Vibes may request changes before approving, and you will be notified by email.

Aegis Mobile vetting does not begin at this step — it is initiated later, when you submit the agent basics. At that point, Vibes submits both the brand and agent basics to Aegis together.

A brand only needs to be submitted once. Once approved, you can provision additional agents under the same brand without resubmitting.

Step 3 — Patch agent details

PATCH https://api.rcsstudio.ai/agents/{agentId}
Authorization: Bearer <access_token>
Content-Type: application/json

Agent details are split into three objects: basics, campaign, and testing. You can patch any combination of them in a single request and update them incrementally before submitting.

Request body

{
  "basics": { ... },
  "campaign": { ... },
  "testing": { ... }
}

basics — agent appearance

Controls how the agent appears to users in their messaging app.

{
  "basics": {
    "name": "Acme Rewards",
    "description": "Rewards program updates and offers",
    "logoUri": "https://cdn.acmecorp.com/logo.png",
    "heroUri": "https://cdn.acmecorp.com/banner.png",
    "color": "#2A7AE4",
    "phoneNumber": { "number": "+18005551234", "label": "Customer Support" },
    "website": { "url": "https://www.acmecorp.com", "label": "Visit us" },
    "email": { "address": "[email protected]", "label": "Email us" },
    "privacyUri": "https://www.acmecorp.com/privacy",
    "termsConditionsUri": "https://www.acmecorp.com/terms"
  }
}

campaign — messaging purpose and consent

Carriers use this to confirm what you'll actually send matches what you've declared. Be specific — vague descriptions are a common rejection reason.

{
  "campaign": {
    "companyOverview": "A national retail brand selling apparel across the US.",
    "agentOverview": "Sends order confirmations, shipping updates, and loyalty rewards to opted-in customers.",
    "interactions": [
      { "type": "TransactionalUpdates" },
      { "type": "LoyaltyOrReward" }
    ],
    "messageExamples": [
      { "messageText": "Your order #12345 has shipped. Track it here: https://track.acme.com/12345" },
      { "messageText": "You've earned 200 rewards points! Your balance is now 1,450 points." },
      { "messageText": "Your return for order #11234 has been processed. Refund arrives in 3–5 business days." }
    ],
    "consentSettings": {
      "optInMethods": [{ "type": "Website" }],
      "ctaText": "Sign up for order updates",
      "ctaLink": "https://www.acmecorp.com/signup",
      "ctaUri": "https://cdn.acmecorp.com/cta-screenshot.png",
      "optInMessage": { "messageText": "You're subscribed to Acme order updates. Reply STOP to opt out." },
      "helpResponse": { "messageText": "Acme Rewards: For help, call 1-800-555-1234 or visit acmecorp.com/help. Reply STOP to opt out." },
      "optOutResponse": "You've been unsubscribed from Acme Rewards messages. No further messages will be sent."
    }
  }
}

testing — carrier testing materials

Carriers test the agent directly before approving it. The link.uri is required; additionalInfo is where you include a preview video URL.

{
  "testing": {
    "link": {
      "messageId": "welcome-message",
      "uri": "https://link.rcsstudio.ai/acme-start"
    },
    "additionalInfo": "Preview video: https://cdn.acmecorp.com/rcs-demo.mp4. Shows opt-in flow, HELP response, STOP response, and core loyalty features."
  }
}

Step 4 — Submit agent

The three submissions must happen in order: basics first, then campaign, then testing.

POST https://api.rcsstudio.ai/agents/{agentId}/submit
Authorization: Bearer <access_token>
Content-Type: application/json

Each call locks that section for review. Once all three are submitted, Vibes compiles the details into an RCS Program Brief and submits it to carriers on your behalf.

{ "type": "basics" }

Check status

There are no webhooks for submission status changes. Poll the brand and agent endpoints to track progress.

GET https://api.rcsstudio.ai/brands/{brandId}
Authorization: Bearer <access_token>

GET https://api.rcsstudio.ai/agents/{agentId}
Authorization: Bearer <access_token>

The response includes a status field on both the brand and agent. See Agent status lifecycle for what each status means and whether any action is required from you.

Key fields to watch on the agent response:

Agent status codes

The API returns more granular status codes than what is shown in the RCS Studio UI. The table below maps each API value to the corresponding status on the Agent status lifecycle page.

Brand status codes

Typical timelines

Once all submissions are in, Vibes handles the rest — you don't interact with Aegis or carriers directly.

Poll GET /agents/:agentId to check status. See Agent status lifecycle for a full description of each status and what, if anything, is required from you.

See also

• Agent status lifecycle — Status reference and what each status means
• Update brand — API reference
• Submit brand — API reference
• Update agent — API reference
• Submit agent — API reference