POST /register

This request registers a group of insider_ids for a given activity_type on Insider One's end in advance. The activity has not started yet.  This step:

• Triggers the collection of push-to-start tokens from devices (via the SDK, for eligible devices).

• Generates an activity_id for the activity. This ID is used in all subsequent calls.

• Filters out devices that fail eligibility checks (e.g., iOS version, push opt-in, and GDPR) and prepares the remaining ones for the activity.

The actual start happens later via /start.

If you want to prepare an activity for "when the time approaches," call /register in advance (e.g., 30 minutes before a match begins) and call /start at the exact start moment. This way the pushes go out smoothly right at the actual start.

Endpoint and headers

POST /api/v1/live-activity/register

Headers

Body parameters

Below are the parameters for the request body.

• activity_type cannot be empty or whitespace-only.

• insider_ids must contain between 1 and 10,000 elements.

• ends_at must be in the future.

• ends_at must be at least 5 minutes from now.

• ends_at must be at most 7 days from now.

The insider_ids upper bound is config-driven (REGISTER_MAX_INSIDER_IDS, default 10,000). Split larger segments across multiple /register calls. Each returns its own activity_id.

Sample body

Below is a sample body for a request.

{
  "activity_type": "OrderTrackingAttributes",
  "insider_ids": [
    "user-123",
    "user-456",
    "user-789"
  ],
  "ends_at": "2026-05-20T14:30:00Z"
}

Body examples

The examples below align with Insider One’s demo app and can be used directly with the 3 ActivityAttributes classes available in the Insider iOS SDK demo app.

Order delivery tracking

{
  "activity_type": "DeliveryActivityAttributes",
  "insider_ids": ["user-123", "user-456"],
  "ends_at": "2026-05-19T10:00:00Z"
}

Workout tracking

{
  "activity_type": "WorkoutActivityAttributes",
  "insider_ids": ["user-789"],
  "ends_at": "2026-05-18T20:00:00Z"
}

Live match score

{
  "activity_type": "MatchActivityAttributes",
  "insider_ids": ["user-100", "user-101", "user-102"],
  "ends_at": "2026-05-18T23:00:00Z"
}

The activity_type values must exactly match the Swift class names in the iOS application.

Sample responses

Success response 200

{
  "status": "success",
  "activity_id": "550e8400-e29b-41d4-a716-446655440000",
  "matched": 950,
  "added": 800,
  "refreshed": 150,
  "removed": 5,
  "skipped": {
    "push_permission_disabled": 30,
    "unsupported_platform": 15,
    "unsupported_os_version": 5,
    "push_to_start_token_missing": 0,
    "user_not_found": 0
  }
}

Below are the fields that return in the response.

Below are the fields in the skipped field.

Partial response examples

Plain success (all eligible)

{
  "status": "success",
  "activity_id": "uuid",
  "matched": 100,
  "added": 100,
  "refreshed": 0,
  "removed": 0,
  "skipped": {
    "push_permission_disabled": 0,
    "unsupported_platform": 0,
    "unsupported_os_version": 0,
    "push_to_start_token_missing": 0,
    "user_not_found": 0
  }
}

Success with skipped

Some insiders are filtered out; the activity is still created.

{
  "status": "success",
  "activity_id": "uuid",
  "matched": 720,
  "added": 720,
  "refreshed": 0,
  "removed": 0,
  "skipped": {
    "push_permission_disabled": 180,
    "unsupported_platform": 60,
    "unsupported_os_version": 35,
    "push_to_start_token_missing": 5,
    "user_not_found": 0
  }
}

Success with GDPR Denied

Insiders who haven't given GDPR consent are both counted and listed in a separate block.

{
  "status": "success",
  "activity_id": "uuid",
  "matched": 945,
  "added": 945,
  "refreshed": 0,
  "removed": 0,
  "skipped": {
    "push_permission_disabled": 0,
    "unsupported_platform": 0,
    "unsupported_os_version": 0,
    "push_to_start_token_missing": 0,
    "user_not_found": 0
  },
  "gdpr_denied_details": [
    {"insider_id": "user-12", "devices_count": 2},
    {"insider_id": "user-77", "devices_count": 1}
  ]
}

Insiders with a missing GDPR field are treated as consenting. Only those with GDPR=false appear in this list.

Partial result on large segments

For very large segments, some profile lookups on Insider One's end may fail transiently. In that case, the response is partially successful.

{
  "status": "success",
  "activity_id": "uuid",
  "matched": 850,
  "added": 850,
  "refreshed": 0,
  "removed": 0,
  "skipped": { ... },
  "partial": true,
  "unprocessed_insider_id_count": 50
}

When you receive partial: true, identify the unprocessed insiders and retry them with a separate /register; the activity is still valid and you can send pushes to the successful devices.

All filtered → 422 NO_ELIGIBLE_DEVICE

If no eligible device remains, the response is 422, and the body contains the filter breakdown.

{
  "error": "no eligible device found for the given insider_ids",
  "code": "NO_ELIGIBLE_DEVICE",
  "skipped": {
    "push_permission_disabled": 35,
    "unsupported_platform": 10,
    "unsupported_os_version": 5,
    "push_to_start_token_missing": 0,
    "user_not_found": 0
  },
  "gdpr_denied_details": [
    {"insider_id": "user-A", "devices_count": 1},
    {"insider_id": "user-B", "devices_count": 1}
  ]
}

You can see why they were filtered out and adjust your segment.

Error responses

Refer to Error Codes for details.

Limitations

• The rate limit is 1,000 requests per minute.

• activity_id is opaque to the customer. It is generated by Insider One; the customer cannot send it. Store this ID. It is referenced in all subsequent calls.

• Re-registering the same insider for the same activity_type: A previously added device is counted as refreshed, and its metadata is renewed. No push is resent, the actual push starts with /start.

• Token collection delay: On newly downloaded apps or on apps with a freshly installed SDK, push-to-start token collection may take a few seconds. If you have very new users, it is normal to see them under the push_to_start_token_missing counter.

• ends_at validity period: The ends_at value determines the validity period of the record on Insider One's end. After this period expires, the activity automatically becomes dead. Always call /end explicitly to deliver a final message to the user.