Service Guide
ENGAGE® Cleanup API Service Guide
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
Clean ENGAGE Content
POST
/federated/outbound/v1/clean/push
Endpoint Details
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.
Tokens are valid for 15 minutes. When the token expires, it should be refreshed using the Get Token endpoint
Prerequisities
Client ID & Client Secret: generated and delivered to integration customers by First Orion
Request
URL
/federated/content/v2/token
Method
POST
Headers
- Content-type: application/json
- X-Federated-Purpose: inform
Body
{
"clientId":<clientId>",
"clientSecret":"<clientSecret>"
}
| Field | Type | Required | Description |
|---|---|---|---|
| clientId | String | Yes | Federated client identifier provided by First Orion |
| clientSecret | String | Yes | Secret code for federated client provided by First Orion and used in the request to retrieve a valid Access Token Recommendation: Protect this value in the same manner as a password |
Response
Success
- Return code: 200 OK
- Response body:
{
"accessToken": "eyJraWQiOiJzVkM5eXczZ2Vtckwzb2ZpbXZCM1BSWGNWc1JhcXJsR0lQSWN0TDhUcXBrPSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiJrdjQ4NmhxYWxsYml2c2t2NnE2M3Zhc2NwIiwidG9rZW5fdXNlIjoiYWNjZXNzIiwic2NvcGUiOiJjb20uZmlyc3Rvcmlvbi5lbmdhZ2UuZmVkZXJhdGlvblwvZmVkZXJhdGVkaW5mb3JtIiwiYXV0aF90aW1lIjoxNTYwMzUyNDc1LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV80WlZGZDBKbXEiLCJleHAiOjE1NjAzNTYwNzUsImlhdCI6MTU2MDM1MjQ3NSwidmVyc2lvbiI6MiwianRpIjoiNzRiZTczOTktZTZmYi00Njk4LWIwMzUtMjdkMzE0YTI4MTdmIiwiY2xpZW50X2lkIjoia3Y0ODZocWFsbGJpdnNrdjZxNjN2YXNjcCJ9.Od3JH7qUV15B7LisXP6oj6elwRn8omZJJbmtWu-X9tVHN9P846nVRQSaWyOqt6a91afdkd5sM7Hs4UoNeWqcIvAio93lAesSEEYxDQrHsi4LpxQ_Fb4nF_9Mk_kPrgfnqmSdRzWhRrkdLhuvrAvbFL6wm14TSKeHX-mYVBe4LqnYA8Ok297YYSVLgBk4lUw1Vb2brUWwpT71ddLE0nUE7rNL69HE1qX9N5zc3uzpsVdU8IqscyZFbwZOCfRaTX7MYAtzj9mFxyumYKVRM5lZcn87i4RETjh4pTtj-8I4l3TrNyu4MGO7EpslgmnPvk04liV6s77JMh3fe1Q3wQNzdQ",
"message": "Success",
"errorCode": 0,
"requestId": "12ab005b-1522-406b-82c9-a2ab9a1ff49
}
| Field | Type | Description |
|---|---|---|
| accessToken | String | Access token used for Authentication in subsequent service requests, i.e., (Authorization: Bearer '') |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Error 500 - Failed to Grant accessToken Error (missing clientId)
- Return code: 500 Internal Server Error
- Response body:
{
"accessToken": null,
"message": "Failed to grant access token",
"errorCode": 500,
"requestId": "5cf3ad7e-0428-491f-a85f-c444487d1523"
}
| Field | Type | Description |
|---|---|---|
| accessToken | String | Null value returned for missing token |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
ENGAGE Clean Content: by trackingId
Cleans the content from ENGAGE-enabled devices by providing a trackingId of a Branded Content Push that has been successfully delivered via Real-Time Push Service.
Prerequisites
Authorization Token : the value for the header Authorization: Bearer Token will be returned by the Get Token service request
Tracking ID : The
requestIdwhich will be returned in the Real-Time Push API for the successfully delivered content
Request
URL
/federated/outbound/v1/clean/push
Method
POST
Headers
- Authorization: Bearer accessToken from Get Token request;
- Content-type : application/json
Body
{
"trackingId": "6c09890d-33c6-412c-956f-f81843506555",
"maxWaitDuration":5
}
| Field | Type | Required | Description |
|---|---|---|---|
| trackingId | String | Yes | Request ID of the content successfully delivered via the Real-Time Push Service. |
| maxWaitDuration | Integer | Yes | Max wait time, in seconds, for a response from the device, to the handset, to pushing content. Recommended value: 3-5 seconds Value can be also passed as 0 if wait time is not needed |
## Response
Success
- Return code: 200 OK
- Response body:
{
"response": "HandsetCleanedContent",
"message": "Success",
"errorCode": "",
"requestId": "3448a679-29b2-49a9-8c1b-759bb221cbfd"
}
| Field | Type | Description |
|---|---|---|
| response | Object | Response object from server |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Response 202 - Attempted
Clean Push was successfully attempted but bNumber is not an ENGAGE-enabled device: Device did NOT cleaned the content
- Return code: 202
- Accepted
- Response body:
{
"response": "BNumberNotActive",
"message": "BNumber is not active in the system.",
"errorCode": "",
"requestId": "989a89a5-7626-4251-bf41-36fe4d1c2081"
}
| Field | Type | Description |
|---|---|---|
| response | Object | Response object from server |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Response 202 - Handset failed to respond within timeout
- Return code: 202
- Accepted
- Response body:
{
"response": "MaxWaitDurationExceeded",
"message": "Handset did not respond within the timeout for this request.",
"errorCode": 0,
"requestId": "d5104cdc-e415-42ab-9375-eecc98929c37"
}
| Field | Type | Description |
|---|---|---|
| response | Object | Response object from server |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Error 400 - Invalid Tracking Id
- Return code: 400
- Bad Request
- Response body:
{
"response": [],
"message": "Invalid request",
"errorCode": 15000,
"requestId": "4daea825-a682-483a-a56f-af2428078ba7"
}
| Field | Type | Description |
|---|---|---|
| response | Object | Response object from server |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Error 400 - Real-Time Push was unsuccessful
- Return code: 400
- Bad Request
- Response body:
{
"response": [],
"message": "The push against trackingId was unsuccessful",
"errorCode": 15000,
"requestId": "4daea825-a682-483a-a56f-af2428078ba7"
}
| Field | Type | Description |
|---|---|---|
| response | Object | Response object from server |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Error 400 - Real-Time Push already expired
- Return code: 400
- Bad Request
- Response body:
{
"response": [],
"message": "The push was expired.",
"errorCode": 15000,
"requestId": "5243fe11-17e8-4a38-8e40-10950c4b61e5"
}
| Field | Type | Description |
|---|---|---|
| response | Object | Response object from server |
| message | String | Message returned from server |
| errorCode | String | Error code returned from server |
| requestId | String | Unique HTTP request made to server |
Error 401 -Bearer token used for Authorization header is invalid
- Return code: 401
- Unauthorized
- Response body: None
Updated 14 days ago
