Message Center API, which powers a customer-facing messaging inbox, allows you to get push notifications of any type delivered to your users during a defined time interval, including the push notifications delivered in Architect journeys and those you sent via mobile app APIs.
Endpoint and Headers
Visit our Postman collection to test this request.
Header | Sample Value | Description | Required |
|---|---|---|---|
Authorization | Bearer {access_token} | Retrieve {access_token} as described in OAuth 2.0 Credentials | Yes |
Content-Type | application/json | This header specifies the media type of the resource. | Yes |
Body Parameters
insider_id and identifiers are mutually exclusive. Send exactly one of them.
Parameter | Description | Data Type | Required |
|---|---|---|---|
insider_id | Insider ID of the target user | String | Conditional |
identifiers | User's identifier information. Identifiers can be Email, Phone Number, UUID (unique user ID), or a custom identifier. The identifiers need to be written in the mentioned case in the request, while the custom attribute needs to be written in the attribute_name format. Instead of the identifiers object, you can also use the insider_id key. | Object | Conditional |
start_date | The start date of the timeline push notifications are delivered within, in timestamp format. | Int (Unix timestamp) | Yes |
end_date | The end date of the timeline push notifications are delivered within, in timestamp format. | Int (Unix timestamp) | Yes |
limit | Number of push notifications you can get in one request. The value can be between 1 and 100. | Integer | Yes |
Sample Body
The sample body below requests user-related data using an identifier (email), a start and end date range, and a limit on the number of records to return.
Before sending the request, replace the values in your request body.
Below is a sample payload with the identifiers object.
curl -X POST 'https://gw.useinsider.com/api/mob/v1/message-center' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data '{
"identifiers": {
"Email": "j.doe@insiderone.com"
},
"start_date": 1633068172,
"end_date": 2143433430,
"limit": 100
}'Below is a sample payload with the insider_id key instead of the identifiers object.
curl -X POST 'https://gw.useinsider.com/api/mob/v1/message-center' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data '{
"insider_id": "user-123",
"start_date": 1751328000,
"end_date": 1753920000,
"limit": 50
}'Sample Responses
The following are some example responses you might receive for your request.
200 OK
The following is a sample response for a successful request with a limit of 3.
[
{
"title": "Sale Alert!",
"message": "50% off everything today",
"image_url": "https://cdn.example.com/banner.png",
"camp_id": 123,
"variant_id": 2,
"camp_type": 0,
"deep_links": "myapp://campaign/123",
"created_at": 1751414400
}
]Below are the response parameters. When nothing matches, the response is an empty array ([]), not a 404.
Field | Type | Notes |
|---|---|---|
title, message | String | Records with an empty title or message are not returned |
image_url | String | When the campaign has an image URL |
camp_id, variant_id, camp_type | Int | Campaign identity |
deep_links | String | When the campaign defines one |
created_at | Int (Unix timestamp) | When the notification was delivered |
400 Bad Request
The following is a sample response for a request where the start date is greater than the end date.
bad payload400 Bad Request
The following is a sample response for a request where the limit is greater than 100.
limit should be between 1 and 100.401 Unauthorized
A request with an invalid API key will return a 401 Unauthorized response. Refer to API Authentication Tokens to get your API key.
Limitations
All functions must be executed with a simple HTTPS POST request.
The rate limit is 5000 requests per minute.
Each request can get push notifications only for one single user.
API returns only delivered pushes. The app_push_delivered event must be available.
The default limit shown here is a standard baseline. If your use case requires higher capacity, feel free to reach out to the Insider One team. We can adjust it to fit your needs.
Authentication
This endpoint is served over the Insider API Gateway and authenticates with OAuth 2.0. Create a credential once in InOne > Settings > Integration Settings > OAuth 2.0 Credentials, exchange it for a bearer token at POST https://gw.useinsider.com/auth/token, and send that token on every call. Token retrieval is not repeated here.
Required scope | Authorizes | Rate limit |
|---|---|---|
mob-get-message-center | POST https://gw.useinsider.com/api/mob/v1/message-center | 60 requests / 60 seconds, burst 20 |
Each scope has its own independent rate-limit bucket. The partner is resolved from the partner claim in your token, so no API key or customer identifier is sent in the request body.
insider_id and identifiers stay mutually exclusive, and the limit must be between 1 and 100. When nothing matches, the response is an empty array ([]), not a 404. The request and response bodies documented above are unchanged from the legacy API key endpoint.
Sample request
curl -X POST 'https://gw.useinsider.com/api/mob/v1/message-center' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data '{
"insider_id": "12345",
"start_date": 1633068172,
"end_date": 2143433430,
"limit": 100
}'
Errors returned by the product
HTTP | Body | Cause |
|---|---|---|
400 | bad payload | The body could not be parsed, or the identifier rule was violated. |
400 | limit should be between 1 and 100. | limit is outside the 1–100 range. |
404 | — | The partner carried in the token could not be resolved. |
500 | — | Transient error on the Insider side. Retry with backoff. |
Errors returned by the gateway
The following responses are produced by the Insider API Gateway before your request reaches the product. They all share the same body shape: {"code":"...","message":"..."}.
HTTP | Body | Cause |
|---|---|---|
401 | {"code":"R1","message":"Invalid Token"} | The token is missing or invalid. |
401 | {"code":"R5","message":"Expired Token"} | The token has expired. Generate a new one. |
401 | {"code":"R6","message":"Invalid Request"} | The token does not carry the mob-get-message-center scope. |
403 | {"code":"R4","message":"IP Restricted"} | The source IP is not authorized on the credential. List both IPv4 and IPv6 ranges; an IPv4-only allowlist rejects IPv6 traffic. |
405 | {"code":"R6","message":"Invalid Request"} | The scope matched, but the HTTP method is wrong. This endpoint accepts POST only. |
429 | {"code":"R3","message":"Rate Limited"} | The scope rate limit was exceeded. Retry with exponential backoff. |
A missing scope returns 401, not 403. 403 means IP restriction only.
A response carrying Via: 1.1 Caddy generally crossed the gateway, which means the error came from the product layer rather than from authentication.
Migration from the API key endpoint
Legacy | OAuth 2.0 | |
|---|---|---|
URL | POST https://mobile.useinsider.com/api/message_center/v1 | POST https://gw.useinsider.com/api/mob/v1/message-center |
Auth | X-INSIDER-API-KEY header | Authorization: Bearer + mob-get-message-center scope |
Request body | Identical. The schema does not change. | |
Response body | Identical. The schema does not change. |
The legacy path stays available. The two paths are independent and never accept each other's credentials.