Messaging · RCS

Request an RCS agent

Requests an RCS agent.

POSThttps://api.pozy.ai/v1/rcs/agents

createRcsAgent

Guides: RCS, Idempotency and safe retries

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys cannot call it. Keys with the messages resource group disabled get 403 resource_group_disabled. Authentication

Headers

Name	Type	Notes
`Idempotency-Key`	string	Up to 255 charactersRetries with the same key return the original result. See Idempotency

Request body

application/json, required

profileIdstringrequired
brandIdstring
brandobject
9 child fields
- displayNamestringrequired
  Up to 100 characters.
- legalNamestringrequired
  Up to 100 characters.
- legalEntityTypestringrequired
  One of LIMITED_LIABILITY_COMPANY, SOLE_PROPRIETORSHIP, PARTNERSHIP, CORPORATION, S_CORPORATION.
- organizationTypestringrequired
  One of PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT.
- websiteUrlstring (URL)required
- taxIdstringrequired
- stockSymbolstring
- addressobjectrequired
  6 child fields
  line1stringrequired
  line2string
  citystringrequired
  statestring
  postalCodestringrequired
  countrystringrequired
  One of US, GB, AT, BD, BR, CD, DE, ES, FR, IN, IT, MX, NG, NL, NO, PT, SE, SG, ZA.
- contactobjectrequired
  5 child fields
  firstNamestringrequired
  lastNamestringrequired
  titlestring
  emailstring (email)required
  phonestringrequired
displayNamestringrequired
Up to 40 characters.
useCasestringrequired
One of MULTI_USE, PROMOTIONAL, TRANSACTIONAL, OTP.
profileobjectrequired
9 child fields
- descriptionstringrequired
  Up to 100 characters.
- logoUrlstring (URL)required
- heroUrlstring (URL)required
- brandColorstringrequired
- privacyPolicyUrlstring (URL)required
- termsUrlstring (URL)required
- phoneobject
  2 child fields
  numberstringrequired
  labelstringrequired
  Up to 25 characters.
- websiteobject
  2 child fields
  urlstring (URL)required
  labelstringrequired
  Up to 25 characters.
- emailobject
  2 child fields
  addressstring (email)required
  labelstringrequired
  Up to 25 characters.
smsFallbackFromstring

Example

curl -X POST "https://api.pozy.ai/v1/rcs/agents" \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "profileId": "6a0b6573846efc28aaa9a3ff",
  "displayName": "Acme",
  "useCase": "MULTI_USE",
  "profile": {
    "description": "A short description",
    "logoUrl": "https://pozy.ai/media/example-1.jpg",
    "heroUrl": "https://pozy.ai/media/example-1.jpg",
    "brandColor": "string",
    "privacyPolicyUrl": "https://pozy.ai/media/example-1.jpg",
    "termsUrl": "https://pozy.ai/media/example-1.jpg"
  }
}'

import { randomUUID } from "node:crypto";

const res = await fetch("https://api.pozy.ai/v1/rcs/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POZY_API_KEY}`,
    "Idempotency-Key": randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    profileId: "6a0b6573846efc28aaa9a3ff",
    displayName: "Acme",
    useCase: "MULTI_USE",
    profile: {
      description: "A short description",
      logoUrl: "https://pozy.ai/media/example-1.jpg",
      heroUrl: "https://pozy.ai/media/example-1.jpg",
      brandColor: "string",
      privacyPolicyUrl: "https://pozy.ai/media/example-1.jpg",
      termsUrl: "https://pozy.ai/media/example-1.jpg"
    }
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.post(
    "https://api.pozy.ai/v1/rcs/agents",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    json={
        "profileId": "6a0b6573846efc28aaa9a3ff",
        "displayName": "Acme",
        "useCase": "MULTI_USE",
        "profile": {
            "description": "A short description",
            "logoUrl": "https://pozy.ai/media/example-1.jpg",
            "heroUrl": "https://pozy.ai/media/example-1.jpg",
            "brandColor": "string",
            "privacyPolicyUrl": "https://pozy.ai/media/example-1.jpg",
            "termsUrl": "https://pozy.ai/media/example-1.jpg",
        },
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

201 on success

agentobject
19 child fields
- idstring
- profileIdstring
- accountIdstring
  Can be null.
- countrystring
- statusstring
  One of requested, changes_requested, brand_vetting, agent_review, testing, launch_review, launching, live, rejected, deactivated.
- displayNamestring
  Up to 40 characters.
- useCasestring
  One of MULTI_USE, PROMOTIONAL, TRANSACTIONAL, OTP.
- profileobject
  9 child fields
  descriptionstringrequired
  Up to 100 characters.
  logoUrlstring (URL)required
  heroUrlstring (URL)required
  brandColorstringrequired
  privacyPolicyUrlstring (URL)required
  termsUrlstring (URL)required
  phoneobject
  2 child fields
  numberstringrequired
  labelstringrequired
  Up to 25 characters.
  websiteobject
  2 child fields
  urlstring (URL)required
  labelstringrequired
  Up to 25 characters.
  emailobject
  2 child fields
  addressstring (email)required
  labelstringrequired
  Up to 25 characters.
- brandobject
  One of:
  Rcs Brand (12 fields)
  displayNamestringrequired
  Up to 100 characters.
  legalNamestringrequired
  Up to 100 characters.
  legalEntityTypestringrequired
  One of LIMITED_LIABILITY_COMPANY, SOLE_PROPRIETORSHIP, PARTNERSHIP, CORPORATION, S_CORPORATION.
  organizationTypestringrequired
  One of PRIVATE_PROFIT, PUBLIC_PROFIT, NON_PROFIT, GOVERNMENT.
  websiteUrlstring (URL)required
  taxIdstringrequired
  stockSymbolstring
  addressobjectrequired
  6 child fields
  line1stringrequired
  line2string
  citystringrequired
  statestring
  postalCodestringrequired
  countrystringrequired
  One of US, GB, AT, BD, BR, CD, DE, ES, FR, IN, IT, MX, NG, NL, NO, PT, SE, SG, ZA.
  contactobjectrequired
  5 child fields
  firstNamestringrequired
  lastNamestringrequired
  titlestring
  emailstring (email)required
  phonestringrequired
  idstring
  statusstring
  One of draft, vetting, verified, rejected.
  createdAtstring (date-time)
- launchRequestobject
  One of:
  Rcs Launch Request (7 fields)
  companyOverviewstringrequired
  Up to 2000 characters.
  agentOverviewstringrequired
  Up to 2000 characters.
  interactionsarray of objectrequired
  At least 1 item.
  2 child fields
  typestringrequired
  One of TRANSACTIONAL_UPDATES, CUSTOMER_SUPPORT, LOYALTY_OR_REWARD, MARKETING_OR_PROMOTIONAL, ACCOUNT_ALERTS, TWO_WAY_CONVERSATION, OTHER.
  descriptionstring
  messageExamplesarray of stringrequired
  At least 3 items. Up to 10 items. Each item: up to 2000 characters.
  consentobjectrequired
  9 child fields
  optInMethodsarray of objectrequired
  At least 1 item.
  2 child fields
  typestringrequired
  One of SMS, WEBSITE, MOBILE_APP, QR_CODE, SALE_POINT, OTHER.
  descriptionstring
  callToActionstringrequired
  callToActionUrlstring (URL)
  callToActionMediaUrlstring (URL)
  doubleOptInbooleanrequired
  doubleOptInMessagestring
  optInMessagestringrequired
  helpResponsestringrequired
  optOutResponsestringrequired
  testVideoUrlstring (URL)required
  additionalInformationstring
  Up to 2000 characters.
- carrierApprovalsarray of object
  6 child fields
  approvalIdstring
  scopestring
  One of carrier, hub, bot.
  statusstring
  One of PENDING, SUBMITTED, APPROVED, REJECTED.
  carrierstring
  Can be null.
  approvedAtstring (date-time)
  Can be null.
  rejectedReasonstring
  Can be null.
- testDevicesarray of object
  3 child fields
  testDeviceIdstring
  phoneNumberstring
  inviteStatusstring
  One of PENDING, ACCEPTED, DECLINED.
- smsFallbackFromstring
  Can be null.
- reviewNotestring
  Can be null.
- declineReasonstring
  Can be null.
- requestedAtstring (date-time)
  Can be null.
- submittedAtstring (date-time)
  Can be null.
- liveAtstring (date-time)
  Can be null.
- createdAtstring (date-time)

201 response

{
  "agent": {
    "id": "6bfebd43ddc270f6d2c56fc5",
    "profileId": "6a0b6573846efc28aaa9a3ff",
    "accountId": "696e0b682d0a31188e7a2ba9",
    "country": "US",
    "status": "requested",
    "displayName": "Acme",
    "useCase": "MULTI_USE",
    "profile": {
      "description": "A short description",
      "logoUrl": "https://pozy.ai/media/example-1.jpg",
      "heroUrl": "https://pozy.ai/media/example-1.jpg",
      "brandColor": "string",
      "privacyPolicyUrl": "https://pozy.ai/media/example-1.jpg",
      "termsUrl": "https://pozy.ai/media/example-1.jpg",
      "phone": {
        "number": "string",
        "label": "string"
      },
      "website": {
        "url": "https://pozy.ai/media/example-1.jpg",
        "label": "string"
      },
      "email": {
        "address": "alex@example.com",
        "label": "string"
      }
    },
    "brand": {
      "displayName": "Acme",
      "legalName": "Acme",
      "legalEntityType": "LIMITED_LIABILITY_COMPANY",
      "organizationType": "PRIVATE_PROFIT",
      "websiteUrl": "https://pozy.ai/media/example-1.jpg",
      "taxId": "6e274285e4e83c5f91aee85e",
      "stockSymbol": "string",
      "address": {
        "line1": "string",
        "line2": "string",
        "city": "string",
        "state": "string",
        "postalCode": "string",
        "country": "US"
      },
      "contact": {
        "firstName": "Acme",
        "lastName": "Acme",
        "title": "Launch day",
        "email": "alex@example.com",
        "phone": "+14155550123"
      },
      "id": "6bfebd43ddc270f6d2c56fc5",
      "status": "draft",
      "createdAt": "2026-10-02T09:00:00.000Z"
    },
    "launchRequest": {
      "companyOverview": "string",
      "agentOverview": "string",
      "interactions": [
        {
          "type": "TRANSACTIONAL_UPDATES",
          "description": "A short description"
        }
      ],
      "messageExamples": [
        "Hello from Pozy"
      ],
      "consent": {
        "optInMethods": [
          {
            "type": "SMS",
            "description": "A short description"
          }
        ],
        "callToAction": "string",
        "callToActionUrl": "https://pozy.ai/media/example-1.jpg",
        "callToActionMediaUrl": "https://pozy.ai/media/example-1.jpg",
        "doubleOptIn": true,
        "doubleOptInMessage": "Hello from Pozy",
        "optInMessage": "Hello from Pozy",
        "helpResponse": "string",
        "optOutResponse": "string"
      },
      "testVideoUrl": "https://pozy.ai/media/example-1.jpg",
      "additionalInformation": "string"
    },
    "carrierApprovals": [
      {
        "approvalId": "66666666666666661f2e3d4c",
        "scope": "carrier",
        "status": "PENDING",
        "carrier": "string",
        "approvedAt": "2026-10-02T09:00:00.000Z",
        "rejectedReason": "string"
      }
    ],
    "testDevices": [
      {
        "testDeviceId": "653426651346b544a97028d1",
        "phoneNumber": "+14155550123",
        "inviteStatus": "PENDING"
      }
    ],
    "smsFallbackFrom": "string",
    "reviewNote": "string",
    "declineReason": "string",
    "requestedAt": "2026-10-02T09:00:00.000Z",
    "submittedAt": "2026-10-02T09:00:00.000Z",
    "liveAt": "2026-10-02T09:00:00.000Z",
    "createdAt": "2026-10-02T09:00:00.000Z"
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is read-only, scoped to other profiles, or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

More in RCS

GETList RCS brands GETList RCS agents GETGet an RCS agent PATCHUpdate an RCS agent DELDeactivate an RCS agent POSTSend the launch filing GETList RCS test phones POSTInvite an RCS test phone DELRemove an RCS test phone POSTUpload an RCS logo or banner POSTSend an RCS message GETCheck RCS capability