---
updatedAt: 2026-06-05T20:14:09.000Z
---

# Realtime Engage SDK

Notify First Orion about a call that is about to be made from aNumber to bNumber

# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "version": "1.0",
    "title": "Branded Communications Exchange",
    "termsOfService": "https://firstorion.com/terms-use/",
    "x-logo": {
      "url": "https://firstorion.com/wp-content/themes/salient-child/img/logo-icon-blue.svg",
      "backgroundColor": "rgba(0,0,0,0)",
      "altText": "First Orion Logo"
    },
    "description": "> Please avoid using APIs that are marked `deprecated`. While the functions / endpoints will work for the time being, they will be deprecated in the next major release of the APIs.\n",
    "license": {
      "url": "change this and name",
      "name": "Apache 2.0"
    }
  },
  "servers": [
    {
      "url": "https://api.firstorion.com",
      "description": "Production Environment"
    },
    {
      "url": "https://api.forp-lab.com",
      "description": "Integration Environment"
    }
  ],
  "components": {
    "schemas": {
      "businessId": {
        "type": "string",
        "description": "System generated unique identifier for the business",
        "example": "719d140e-fd6c-4d59-9241-3dee71b38320"
      },
      "phoneNumber": {
        "type": "string",
        "description": "Phone number in E.164 format.",
        "minimum": 7,
        "maximum": 15,
        "pattern": "^\\+[1-9]\\d{1,14}$",
        "example": "+12125554200"
      },
      "programId": {
        "type": "string",
        "description": "System generated unique identifier for the program",
        "example": "df567c99-9354-47e5-b30f-88ee7cbfeab4"
      },
      "phoneNumberId": {
        "type": "string",
        "readOnly": true,
        "description": "System generated unique identifier of a phone number",
        "example": "0dd9a02c-03f9-49d5-aa83-7e9498fbe74f"
      },
      "callPurposeCode": {
        "type": "string",
        "description": "The most common purpose why the phone number is making calls. Must be one of `GET /exchange/v1/reference-data/call-purposes`",
        "example": "CS"
      },
      "DeliveryChannelEngageAsset-subject": {
        "type": "string",
        "description": "1 to 160 character long description why the call is being made",
        "minimum": 1,
        "maximum": 160,
        "example": "We have detected a fraudulent transaction on your credit card"
      },
      "PreCall-Engage-Realtime-Request": {
        "type": "object",
        "properties": {
          "aNumbers": {
            "type": "array",
            "description": "List of phone numbers that are used to call bNumber",
            "items": {
              "$ref": "#/components/schemas/phoneNumber"
            },
            "minimum": 1
          },
          "bNumber": {
            "type": "string",
            "description": "Terminating party Phone Number in E.164 format.",
            "minimum": 7,
            "maximum": 15,
            "pattern": "^\\+[1-9]\\d{1,14}$",
            "example": "+12125554201"
          },
          "programId": {
            "$ref": "#/components/schemas/programId"
          },
          "businessId": {
            "$ref": "#/components/schemas/businessId"
          },
          "customTrackingId": {
            "type": "string",
            "description": "User defined tracking id for the Engage calling campaign.",
            "example": "a0ceb54b-00a4-4803-9bfe-ac94c4a5dfd1"
          },
          "keepAfterCall": {
            "type": "boolean",
            "description": "Should the contact card be left on the device after the call is completed",
            "default": false,
            "example": false
          },
          "maxWaitDuration": {
            "type": "integer",
            "description": "To be filled in",
            "minimum": 1,
            "maximum": 200,
            "default": 90,
            "example": 90
          },
          "targetAppId": {
            "type": "string",
            "description": "To be filled in",
            "example": "7295b646-8718-4ce0-9b9e-511e810f0bfd"
          },
          "subject": {
            "$ref": "#/components/schemas/DeliveryChannelEngageAsset-subject"
          },
          "ttlSeconds": {
            "type": "integer",
            "minimum": 60,
            "maximum": 6000,
            "default": 3600,
            "example": 3600
          }
        },
        "required": [
          "aNumbers",
          "bNumber",
          "programId"
        ]
      },
      "PreCall-Engage-Realtime-Response": {
        "properties": {
          "rejectedPhoneNumbers": {
            "type": "array",
            "description": "List of originating phone numbers that cannot be used",
            "items": {
              "type": "object",
              "properties": {
                "callPurposeCode": {
                  "$ref": "#/components/schemas/callPurposeCode"
                },
                "phoneNumberId": {
                  "$ref": "#/components/schemas/phoneNumberId"
                },
                "phoneNumber": {
                  "$ref": "#/components/schemas/phoneNumber"
                },
                "rejectionReason": {
                  "type": "string",
                  "description": "Reason why the number was rejected",
                  "example": "NUMBER_NOT_SET_FOR_AUTHENTICATED_CALLS"
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized"
      },
      "Forbidden": {
        "description": "Forbidden"
      },
      "PrecallDeliveryNotFound": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "Response",
              "properties": {
                "body": {
                  "type": "object",
                  "nullable": true,
                  "example": null
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Error code",
                      "example": 404
                    },
                    "message": {
                      "type": "string",
                      "description": "Description of the error",
                      "example": "delivery channel not found"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "EngageBadRequest": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "Response",
              "properties": {
                "body": {
                  "type": "object",
                  "nullable": true,
                  "example": null
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Error code",
                      "example": 400
                    },
                    "message": {
                      "type": "string",
                      "description": "Description of the error",
                      "example": "object validation failed for field .aNumbers: value is required"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-tagGroups": [
    {
      "name": "Authentication",
      "tags": [
        "Authentication",
        "OAuth2.0"
      ]
    },
    {
      "name": "Businesses",
      "tags": [
        "Businesses",
        "Business Addresses",
        "Business Contacts",
        "Business Images",
        "Business API Keys",
        "Business Units"
      ]
    },
    {
      "name": "Phone Numbers",
      "tags": [
        "Business Phone Numbers",
        "Business Unit Phone Numbers",
        "CallerName aNumbers"
      ]
    },
    {
      "name": "Programs",
      "tags": [
        "Programs",
        "Schedules"
      ]
    },
    {
      "name": "Program Delivery Channels",
      "tags": [
        "Delivery Channels",
        "CallerName",
        "CallerImage",
        "Blocking",
        "Engage SDK"
      ]
    },
    {
      "name": "Call Authentication",
      "tags": [
        "Call Authentication",
        "Call Authentication V2",
        "PreCall Engage SDK"
      ]
    },
    {
      "name": "Reference Data",
      "tags": [
        "Employee Count Ranges",
        "Daily Call Count Ranges",
        "Industries",
        "Call Purposes"
      ]
    },
    {
      "name": "Utilities",
      "tags": [
        "Phone Number Verification"
      ]
    }
  ],
  "paths": {
    "/exchange/v1/calls/push/engage": {
      "summary": "Call Authentication APIs",
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "required": true,
          "schema": {
            "type": "string"
          },
          "example": "<token>",
          "description": "Access Token"
        }
      ],
      "post": {
        "summary": "Realtime Engage SDK",
        "description": "Notify First Orion about a call that is about to be made from aNumber to bNumber",
        "operationId": "PostPreCallEngageRealtime",
        "tags": [
          "PreCall Engage SDK"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PreCall-Engage-Realtime-Request"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "body": {
                      "$ref": "#/components/schemas/PreCall-Engage-Realtime-Response"
                    },
                    "error": {
                      "example": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/EngageBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/PrecallDeliveryNotFound"
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```