Regal

Regal Branded Phone Numbers API

The Branded Phone Numbers API at api.regal.ai/v1/brandedPhoneNumbers lets you register, update, and remove branded caller ID and spam remediation entries on a per-carrier, per-feature basis. POST creates a new registration tying a phoneNumber to a businessProfileId and a carrierFeatures array (with brandingNameShort, brandingNameLong, internalName, reportingGroup, and one of spamRemediation or brandedCallerId enabled). PATCH updates the registration partially. DELETE removes it once all carrier submissions are inactive. The surface is rate limited to 10 requests per second.

Regal Branded Phone Numbers API is one of 5 APIs that Regal publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 1 JSON Schema definition.

Tagged areas include Branded Caller ID, Phone Numbers, Trust Center, and Carrier Registration. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, 1 Naftiko capability spec, and 1 JSON Schema.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.1.0
info:
  title: Regal Branded Phone Numbers API
  version: '1.0'
  summary: Register, update, and remove branded caller ID and spam remediation entries.
  description: >-
    Branded Phone Numbers in Regal control how a tenant's outbound numbers
    appear on recipients' devices via carrier-level branded caller ID and spam
    remediation. Each registration ties a phoneNumber to a businessProfileId
    and a carrierFeatures array describing which features (spamRemediation or
    brandedCallerId) are enabled per carrier. POST is used for first-time
    registration only; PATCH is used for partial updates; DELETE removes a
    registration once all carrier submissions are inactive.
  contact:
    name: Regal Support
    email: [email protected]
    url: https://support.regal.ai
  license:
    name: Proprietary
    url: https://www.regal.ai/terms-of-service
servers:
  - url: https://api.regal.ai/v1
    description: Production v1 Regal API
security:
  - ApiKeyAuth: []
tags:
  - name: Branded Phone Numbers
    description: Carrier-level branded caller ID and spam remediation
paths:
  /brandedPhoneNumbers:
    post:
      summary: Post Branded Phone Number
      operationId: postBrandedPhoneNumber
      description: Register a new branded phone number with one or more carriers.
      tags:
        - Branded Phone Numbers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandedPhoneNumberCreate'
      responses:
        '201':
          description: Phone number registered.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandedPhoneNumber'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/RateLimited'
  /brandedPhoneNumbers/{phoneNumber}:
    parameters:
      - name: phoneNumber
        in: path
        required: true
        schema:
          type: string
        description: The branded phone number identifier (E.164).
    patch:
      summary: Patch Branded Phone Number
      operationId: patchBrandedPhoneNumber
      description: Partially update a branded phone number registration.
      tags:
        - Branded Phone Numbers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BrandedPhoneNumberPatch'
      responses:
        '200':
          description: Successfully updated phone number.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandedPhoneNumber'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      summary: Delete Branded Phone Number
      operationId: deleteBrandedPhoneNumber
      description: >-
        Remove a branded phone number registration. Phone numbers with active
        carrier submissions cannot be deleted; opt out of all carrier features
        and wait for approval before retrying.
      tags:
        - Branded Phone Numbers
      responses:
        '200':
          description: Phone number deleted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    BrandedPhoneNumber:
      type: object
      properties:
        phoneNumber:
          type: string
        businessProfileId:
          type: string
        brandingNameShort:
          type: string
        brandingNameLong:
          type: string
        internalName:
          type: string
        reportingGroup:
          type: string
        carrierFeatures:
          type: array
          items:
            $ref: '#/components/schemas/CarrierFeature'
    BrandedPhoneNumberCreate:
      type: object
      required:
        - phoneNumber
        - businessProfileId
        - carrierFeatures
      properties:
        phoneNumber:
          type: string
        businessProfileId:
          type: string
        carrierFeatures:
          type: array
          items:
            $ref: '#/components/schemas/CarrierFeature'
        brandingNameShort:
          type: string
        brandingNameLong:
          type: string
        internalName:
          type: string
        reportingGroup:
          type: string
    BrandedPhoneNumberPatch:
      type: object
      properties:
        businessProfileId:
          type: string
        carrierFeatures:
          type: array
          items:
            $ref: '#/components/schemas/CarrierFeature'
        brandingNameShort:
          type: string
        brandingNameLong:
          type: string
        internalName:
          type: string
        reportingGroup:
          type: string
    CarrierFeature:
      type: object
      properties:
        carrier:
          type: string
          description: Carrier identifier (e.g., att, verizon, tmobile).
        spamRemediation:
          type: boolean
        brandedCallerId:
          type: boolean
        status:
          type: string
          description: >-
            Submission status (e.g., submitted.optIn, approved.optIn,
            submitted.optOut, pending.optIn, pending.optOut).
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate Limit Exceeded (10 RPS)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Regal Branded Phone Numbers API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification