Regal

Regal Events API

The Regal Events API is a single high-throughput ingest endpoint (POST https://events.regalvoice.com/events) that creates or updates a contact and records a custom event on the contact profile. The body uses a userId plus a traits object (phones, emails, firstName, lastName, address, custom properties) and a top-level name/properties pair describing the event. Identity resolution iterates identifiers in the order primary phone > any other phone > primary email > any other email > userId. A contact must have at least one phone or email to be considered contactable. Authenticated via API key in the Authorization header. Rate limited to 300 requests per second by default. This is the same endpoint that triggers Journeys (and therefore outbound calls, SMS journeys, and reminder sequences) when paired with the correct event name and TCPA opt-in flags.

Regal Events 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 2 JSON Schema definitions.

Tagged areas include Events, Contacts, Identity Resolution, Ingestion, and Custom Events. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, a JSON-LD context, 1 Naftiko capability spec, and 2 JSON Schemas.

Documentation GitHub OpenAPI

OpenAPI Specification

openapi: 3.1.0
info:
  title: Regal Events API
  version: '1.0'
  summary: Custom Events ingestion endpoint for contacts and event tracking on Regal.
  description: >-
    The Regal Events API is a single ingest endpoint that creates a contact,
    updates a contact, or adds a custom event to an existing contact profile.
    Identity resolution iterates identifiers in the order primary phone > any
    other phone > primary email > any other email > userId. A contact must have
    at least one phone or email to be considered contactable in Regal. The same
    endpoint triggers Journeys (and outbound calls / SMS sequences) when the
    event name matches a configured Journey trigger and the destination phone
    carries a voiceOptIn or smsOptIn subscription flag for TCPA compliance.
  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://events.regalvoice.com
    description: Production custom events ingest endpoint
security:
  - ApiKeyAuth: []
tags:
  - name: Events
    description: Contact creation, update, and custom event tracking
paths:
  /events:
    post:
      summary: Post Custom Event
      operationId: postCustomEvent
      description: >-
        Creates or updates a contact profile and records a custom event against
        the resolved profile. At least one phone or email must be present in
        traits for the contact to be considered contactable. Events whose name
        matches a Journey trigger will enroll the contact into that Journey.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomEvent'
            examples:
              leadFormSubmitted:
                summary: Lead Form Submitted
                value:
                  userId: '12345'
                  traits:
                    firstName: Jane
                    lastName: Doe
                    phones:
                      - phoneNumber: '+15551234567'
                        isPrimary: true
                        label: mobile
                        voiceOptIn:
                          subscribed: true
                        smsOptIn:
                          subscribed: true
                    emails:
                      - emailAddress: [email protected]
                        isPrimary: true
                        emailOptIn:
                          subscribed: true
                  name: Lead Form Submitted
                  properties:
                    course: Intro to AI
                    source: marketing-site
                  originalTimestamp: '2026-05-24T15:00:00Z'
                  eventSource: Website
      responses:
        '200':
          description: Request Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    examples:
                      - accepted
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key issued by Regal Support ([email protected]). Must be sent in the
        Authorization header on every request.
  schemas:
    CustomEvent:
      type: object
      required:
        - traits
      properties:
        userId:
          type: string
          description: External system identifier for the contact.
        traits:
          $ref: '#/components/schemas/ContactTraits'
        name:
          type: string
          description: Event name. Used to enroll contacts into matching Journeys.
        properties:
          type: object
          additionalProperties: true
          description: Event-specific properties.
        originalTimestamp:
          type: string
          description: ISO 8601 timestamp when the event originally occurred.
        eventSource:
          type: string
          description: Source system that emitted the event (e.g., Website, CRM, Backend).
    ContactTraits:
      type: object
      description: Identifiers and attributes describing the contact.
      properties:
        firstName:
          type: string
        lastName:
          type: string
        phones:
          type: array
          items:
            $ref: '#/components/schemas/PhoneTrait'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/EmailTrait'
        address:
          $ref: '#/components/schemas/Address'
      additionalProperties: true
    PhoneTrait:
      type: object
      required:
        - phoneNumber
      properties:
        phoneNumber:
          type: string
        isPrimary:
          type: boolean
        label:
          type: string
          description: Label such as mobile, home, work.
        voiceOptIn:
          $ref: '#/components/schemas/OptInState'
        smsOptIn:
          $ref: '#/components/schemas/OptInState'
    EmailTrait:
      type: object
      required:
        - emailAddress
      properties:
        emailAddress:
          type: string
        isPrimary:
          type: boolean
        label:
          type: string
        emailOptIn:
          $ref: '#/components/schemas/OptInState'
    OptInState:
      type: object
      properties:
        subscribed:
          type: boolean
        timestamp:
          type: string
        source:
          type: string
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
        country:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate Limit Exceeded (300 RPS default)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

Regal Events API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification