--- updatedAt: 2026-03-02T11:14:43.000Z --- # Service Guide [block:api-header] { "title": "ENGAGE® Federated Batch Push Service Guide" } [/block] [block:callout] { "type": "info", "title": "Prerequisites", "body": "Before using the Federated Batch Push Service, the following items must be configured in the Branded Communication Content Portal. \n\n**Assets** – graphics that display on a device during an incoming call \n\n**Program Content** – associated content that will be displayed on a mobile device when a call is received \n\n**aNumbers** – any originating or outgoing numbers used for calling that must be configured in the Content Portal before any branded communication content may be delivered" } [/block] ## U.S. Base URL ## International Base URL ## Open Endpoints Open endpoints do not require authentication. ### Get Token **POST** /federated/content/v2/token ## Endpoints Requiring Authentication **Endpoints for checking the health of previously granted Access Token:** ### Check Token Health **GET** /federated/content/v2/token/health **Endpoints for Batch pushing ENGAGE content to enabled devices:** ### Push ENGAGE Content **POST** /federated/outbound/v2/batch [block:api-header] { "title": "Endpoint Details" } [/block] ## Get Token Get Token returns an access token to be used as Authorization header for all Metrics service requests. This request should be the prerequisite for subsequent service requests. [block:callout] { "type": "warning", "body": "Tokens are valid for 15 minutes. When the token expires, it should be refreshed using the **Get Token** endpoint" } [/block] [block:callout] { "type": "info", "title": "Prerequisities", "body": "**Client ID & Client Secret** : generated and delivered to integration customers by First Orion" } [/block] ## Request ### URL /federated/content/v2/token ### Method **POST** ### Headers * **Content-type**: application/json * **X-Federated-Purpose**: inform ## Body [block:code] { "codes": [ { "code": "{\n\t\t\"clientId\": \"\",\n \"clientSecret\": \"\"\n} ", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Required", "0-0": "clientId", "0-1": "String", "h-3": "Description", "0-2": "Yes", "0-3": "Federal client identifier provided", "1-0": "clientSecret", "1-1": "String", "1-2": "Yes", "1-3": "Secret code for federated client provided by First Orion and used in the request to retrieve a valid Access Token \n**Recommendation:** Protect this value in the same manner as a password" }, "cols": 4, "rows": 2 } [/block] ## Response ### Success * Return code: **200 OK** * Response body: [block:code] { "codes": [ { "code": "{\n \"accessToken\": \"eyJraWQiOiJzVkM5eXczZ2Vtckwzb2ZpbXZCM1BSWGNWc1JhcXJsR0lQSWN0TDhUcXBrPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJrdjQ4NmhxYWxsYml2c2t2NnE2M3Zhc2NwIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJjb20uZmlyc3Rvcmlvbi5lbmdhZ2UuZmVkZXJhdGlvblwvZmVkZXJhdGVkaW5mb3JtIiwiYXV0aF90aW1lIjoxNTYwMzUyNDc1LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV80WlZGZDBKbXEiLCJleHAiOjE1NjAzNTYwNzUsImlhdCI6MTU2MDM1MjQ3NSwidmVyc2lvbiI6MiwianRpIjoiNzRiZTczOTktZTZmYi00Njk4LWIwMzUtMjdkMzE0YTI4MTdmIiwiY2xpZW50X2lkIjoia3Y0ODZocWFsbGJpdnNrdjZxNjN2YXNjcCJ9.Od3JH7qUV15B7LisXP6oj6elwRn8omZJJbmtWu-X9tVHN9P846nVRQSaWyOqt6a91afdkd5sM7Hs4UoNeWqcIvAio93lAesSEEYxDQrHsi4LpxQ_Fb4nF_9Mk_kPrgfnqmSdRzWhRrkdLhuvrAvbFL6wm14TSKeHX-mYVBe4LqnYA8Ok297YYSVLgBk4lUw1Vb2brUWwpT71ddLE0nUE7rNL69HE1qX9N5zc3uzpsVdU8IqscyZFbwZOCfRaTX7MYAtzj9mFxyumYKVRM5lZcn87i4RETjh4pTtj-8I4l3TrNyu4MGO7EpslgmnPvk04liV6s77JMh3fe1Q3wQNzdQ\",\n \"message\": \"Success\",\n \"errorCode\": 0,\n \"requestId\": \"12ab005b-1522-406b-82c9-a2ab9a1ff49d\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "accessToken", "0-1": "String", "0-2": "Access token used for Authentication in subsequent service requests, i.e., (Authorization: Bearer '')", "1-0": "message", "1-1": "String", "1-2": "Message returned from server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block] ### Error 500 - Failed to grant accessToken error (missing clientId) * Return code: **500 Internal Server Error** * Response body: [block:code] { "codes": [ { "code": "{\n \"accessToken\": null,\n \"message\": \"Failed to grant access token\",\n \"errorCode\": 500,\n \"requestId\": \"5cf3ad7e-0428-491f-a85f-c444487d1523\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "accessToken", "0-1": "String", "0-2": "Null value returned for missing token", "1-0": "message", "1-1": "String", "1-2": "Message returned from server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "title": "Check Token Health" } [/block] Returns health of access token used as Authentication header. Tokens should be refreshed after the current Token has expired. [block:callout] { "type": "success", "body": "A healthy token will return a **200 OK** response and token details in the response body" } [/block] [block:callout] { "type": "danger", "body": "An expired token will return a **401 Unauthorized** response and should be refreshed" } [/block] [block:callout] { "type": "info", "title": "Prerequisities", "body": "The value for the header **Authorization: Bearer Token** will be returned by the **Get Token** service request" } [/block] ## Request ### URL /federated/content/v2/token/health ### Method **GET** ### Headers * **Content-type:** application/json * **Authorization:** Bearer Token ## Response ### Success * Return code: **200 OK** * Response body: [block:code] { "codes": [ { "code": "{\n \"accessToken\": null,\n \"message\": \"Healthy\",\n \"errorCode\": \"\",\n \"requestId\": \"5c79f9a0-447e-4093-87d8-05bdd25e9200\"\n}", "language": "json", "name": null } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "accessToken", "0-1": "String", "0-2": "Access token used for Authentication in subsequent service requests, i.e., (Authorization: Bearer Token)", "1-0": "message", "1-1": "String", "1-2": "Message returned from server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block] ### Error 401 - accessToken invalid or expired error * Return code: **401 Unauthorized** * Response body: **None** [block:api-header] { "title": "ENGAGE Batch Push Content: aNumber List" } [/block] Delivers content to multiple ENGAGE-enabled devices by providing a list of aNumbers. [block:callout] { "type": "info", "title": "Prerequisites", "body": "**Authorization Token**: the value for the header **Authorization: Bearer Token** will be returned by the **Get Token** service request\n\n**Program Content UUID**: the associated ENGAGE Program to be delivered as an enhanced experience to ENGAGE-enabled handsets. Programs are set up and configured in the Content Portal – where the Program Content UUID can be found" } [/block] ## Request ### URL /federated/outbound/v2/batch?programContentUuid= **{programContentUuid}** ### Method **POST** ### Headers * **Authorization:** Bearer accessToken from Get Token request; * **Content-type** : application/json ### Query Parameters * **programContentUuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX** * 3e1b9b27-d1f9-4c8d-800f-bb534d6928d6 [block:parameters] { "data": { "h-0": "Field", "h-1": "Tyoe", "h-2": "Required", "h-3": "Desciption", "0-0": "programContentUuid", "0-1": "String", "0-2": "Yes", "0-3": "UUID associated to an ENGAGE program being delivered to device" }, "cols": 4, "rows": 1 } [/block] ## Body – With List of aNumbers [block:code] { "codes": [ { "code": "{\n \"destinations\": [\n {\n \"bNumber\": \"+15018902005\",\n \"personalization\": {\n \"MY_VAR\": \"Put Custom Text Here\"\n },\n \"customTrackingId\": \"custom-tracking-1\"\n },\n {\n \"bNumber\": \"+14258309029\",\n \"personalization\": {\n \"MY_VAR\": \"Put Custom Text Here\"\n },\n \"customTrackingId\": \"custom-tracking-2\"\n }\n ],\n \"aNumbers\": [\n \"+5014008029\",\n \"+5013509988\"\n ],\n \"notBefore\": \"2020-02-10T16:00:00Z\",\n \"ttlSeconds\": \"3600\",\n \"keepAfterCall\": \"false\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Required", "h-3": "Description", "0-0": "destinations", "0-1": "Array", "0-2": "Yes", "1-0": "destinations[0].bNumber", "1-1": "String", "1-2": "Yes", "2-0": "destinations[0].personalization.MY_VAR", "2-1": "String", "2-2": "No", "3-0": "destinations[0].customTrackingId", "3-1": "String", "3-2": "No", "3-3": "Optional ID for client-side tracking", "4-0": "aNumbers", "4-1": "Array String", "4-2": "Yes\nCannot send aNumber Group ID", "5-0": "notBefore", "5-1": "DateTime(UTC)", "5-2": "No", "5-3": "Datetime set before sending content to devices", "6-0": "ttlSeconds", "6-1": "Integer", "6-2": "Yes", "7-0": "keepAfterCall", "7-1": "Boolean", "7-2": "No", "0-3": "List of objects with bNumbers to push content to devices", "1-3": "Device number that will display program content when a call is received after a successful push \nMust be **E.164** format", "2-3": "Custom text sent to bNumber and displayed during call\n**Recommended value: 20** \n**First Orion best practice: maximum of 20 characters as messages over 20 characters may not display correctly on all devices**", "4-3": "Originating numbers calling a bNumber. aNumber must be previously uploaded in the Branded Communication Content Portal \n**List of up to 400 ANumbers in E.164 format**\n**Cannot send UUID**", "6-3": "Duration, in seconds, for content to live on the device following successful content push\n**Default is 3600** \n**Recommended value: 960 seconds** \n**First Orion best practice: set the TTL to 16 minutes**", "7-3": "Set if content should be kept on device after call\n**Default is false** \n**Recommended value: false** \n**First Orion best practice: do not keep content on the device after a call or successful push**" }, "cols": 4, "rows": 8 } [/block] [block:api-header] { "title": "ENGAGE Batch Push Content: aNumber Group UUID" } [/block] Delivers content to multiple ENGAGE-enabled devices by providing an aNumber Group UUID – configured and located in the Content Portal. [block:callout] { "type": "info", "title": "Prerequisites", "body": "**Authorization Token**: the value for the header **Authorization: Bearer Token** will be returned by the **Get Token** service request\n\n**Program Content UUID**: the associated ENGAGE Program to be delivered as an enhanced experience to ENGAGE-enabled handsets. Programs are set up and configured in the Content Portal – where the Program Content UUID can be found\n\n**aNumber Group UUID**: pushing content using an aNumber Group UUID configured in the Content Portal. The UUID can be identified in the Outbound Calling Numbers -> Grouping Numbers section" } [/block] ## Request ### URL /federated/outbound/v2/batch?programContentUuid=**{programContentUuid}** ### Method **POST** ### Headers * **Authorization:** Bearer accessToken from Get Token request * **Content-type** : application/json ### Query Parameters * **programContentUuid=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX** * 3e1b9b27-d1f9-4c8d-800f-bb534d6928d6 [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Required", "h-3": "Description", "0-0": "programContentUuid", "0-1": "String", "0-2": "Yes", "0-3": "UUID associated to ENGAGE program being delivered to device" }, "cols": 4, "rows": 1 } [/block] ## Body – aNumber Group [block:code] { "codes": [ { "code": "{\n \"destinations\": [\n {\n \"bNumber\": \"+15018902005\",\n \"personalization\": {\n \"MY_VAR\": \"Put Custom Text Here\"\n },\n \"customTrackingId\": \"custom-tracking-1\"\n },\n {\n \"bNumber\": \"+14258309029\",\n \"personalization\": {\n \"MY_VAR\": \"Put Custom Text Here\"\n },\n \"customTrackingId\": \"custom-tracking-2\"\n }\n ],\n \"aNumberGroupId\": \"935b91a0-f2fb-4c43-b629-63fea6634512\",\n \"notBefore\": \"2020-02-10T16:00:00Z\",\n \"ttlSeconds\": \"3600\",\n \"keepAfterCall\": \"false\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Required", "h-3": "Description", "0-0": "destination", "0-1": "Array", "0-2": "Yes", "1-0": "destinations[0].bNumber", "1-1": "String", "1-2": "Yes", "2-0": "destinations[0].personalization.MY_VAR", "2-1": "String", "2-2": "No", "3-0": "destinations[0].customTrackingId", "4-0": "aNumbers", "5-0": "notBefore", "6-0": "ttlSeconds", "7-0": "keepAfterCall", "3-1": "String", "4-1": "Array String", "5-1": "DateTime(UTC)", "7-1": "Boolean", "6-1": "Integer", "3-2": "No", "4-2": "Yes \n\nCannot send aNumber Group ID", "5-2": "No", "6-2": "Yes", "7-2": "No", "0-3": "List of objects with bNumbers to push content to devices", "1-3": "Device number that will display program content when a call is received after a successful push\n**Must be E.164 format**", "2-3": "Custom text sent to bNumber and displayed during call\n**Recommended value: 20** \n**First Orion best practice: maximum of 20 characters as messages over 20 characters may not display correctly on all devices**", "3-3": "Optional ID for client-side tracking", "4-3": "Originating numbers calling a bNumber. aNumber must be previously uploaded in the Branded Communication Content Portal\n**List of up to 400 aNumbers in E.164 format**\n**Cannot send UUID**", "5-3": "Datetime set before sending content to devices", "6-3": "Duration, in seconds, for content to live on the device following successful content push \n**Default is 3600**\n**Recommended value: 960 seconds**\n**First Orion best practice: set the TTL to 16 minutes**", "7-3": "Set if content should be kept on device after call\n**Default is false**\n** Recommended value:** false \n**First Orion best practice: do not keep content on the device after a call or successful push**" }, "cols": 4, "rows": 8 } [/block] ## Response ### Success * Return code: **200** * **OK** * Response body: [block:code] { "codes": [ { "code": "{\n \"response\": \"success\",\n \"message\": null,\n \"errorCode\": \"\",\n \"requestId\": \"329f83c4-38ca-4760-a18a-3fb44962c536\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "response", "0-1": "Object", "0-2": "Response object from server", "1-0": "message", "1-1": "String", "1-2": "Message returned from server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block] ### Error 401 - Bearer token used for Authorization header is invalid * Return code: **401** * **Unauthorized** * Response body: **None** ### Response 200 - One or more aNumbers being sent is not associated with the Service Provider making request * Return code: **200** * **OK** * Response body: [block:code] { "codes": [ { "code": "{\n \"response\": \"Not allowed to use one or more anumbers.\",\n \"message\": \"Batch push could not complete push successfully.\",\n \"errorCode\": 200,\n \"requestId\": \"51934465-cc14-4e68-97a0-af7d6faf9f55\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "response", "0-1": "Object", "0-2": "Response object from server", "1-0": "message", "1-1": "String", "1-2": "Message returned from server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block] ### Error 400 - Program used not correctly configured * Return code: **400** * **Unauthorized** * Response body: [block:code] { "codes": [ { "code": "{\n \"response\": \"Invalid program setup on this program\",\n \"message\": \"Batch push could not complete push successfully.\",\n \"errorCode\": 400,\n \"requestId\": \"e9a76f6b-b921-4ffa-b6f2-1a29334073c4\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "response", "0-1": "Object", "0-2": "Response object from server", "1-0": "message", "1-1": "String", "1-2": "Message returned rom server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block] ### Error 400 - Missing aNumber or aNumber GroupID field or field value * Return code: **400** * **Bad Request** * Response body: [block:code] { "codes": [ { "code": "{\n \"response\": \"Must send aNumbers or a valid ANumberGroupId\",\n \"message\": \"Batch could not complete push successfully.\",\n \"errorCode\": 400,\n \"requestId\": \"04707ac5-36e1-42f1-b747-355fad2d772b\"\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Type", "h-2": "Description", "0-0": "response", "0-1": "Object", "0-2": "Response object from server", "1-0": "message", "1-1": "String", "1-2": "Message returned from server", "2-0": "errorCode", "2-1": "String", "2-2": "Error code returned from server", "3-0": "requestId", "3-1": "String", "3-2": "Unique HTTP request made to server" }, "cols": 3, "rows": 4 } [/block]