Peer Events Overview

Note

AI Context

  • Complexity: Low

  • Cost: Free (read-only query against an existing log)

  • Async: No. GET /contact_peer_events is synchronous and returns results immediately.

VoIPBIN’s Peer Events API returns the raw, unfiltered log of peer/local address activity recorded by the platform. As of the Contact Interactions retirement (see below), GET /contact_interactions now returns this same raw, unfiltered log via a legacy-compatible path — it no longer applies identity resolution or CRM eligibility filtering. Both endpoints may include rows for internal-resource peer types (agent extensions, AI participants, conference legs, SIP trunks); applications must filter or label these rows themselves before customer-facing display.

Use GET /contact_peer_events for new integrations. GET /contact_interactions is kept only for backward compatibility with existing callers and additionally accepts an address_id filter that contact_peer_events does not support; it carries no other advantage over contact_peer_events going forward.

With the Peer Events API you can:

  • Search all recorded activity for a single peer_type + peer_target pair (e.g. a specific phone number)

  • Search all recorded activity across every address registered to a contact

  • Page through results using a cursor-based next_page_token

How Peer Events Relates To Contact Interactions

+-----------------------------------------------------------------------+
|         Same Raw Data, Two Paths (one legacy, one current)            |
+-----------------------------------------------------------------------+

GET /contact_interactions (legacy)           GET /contact_peer_events (current)
+--------------------------+                  +--------------------------+
| Raw, unfiltered          |                  | Raw, unfiltered          |
| Includes internal noise  |                  | Includes internal noise |
| (agent/ai/conference)    |                  | (agent/ai/conference)   |
| + supports address_id    |                  |                          |
+--------------------------+                  +--------------------------+
          |                                             |
          v                                             v
    Kept for existing callers                   Recommended for new
    of the legacy endpoint                       integrations

Both endpoints return the identical unfiltered response shape and can be filtered by contact_id or by a single peer_type + peer_target pair; contact_interactions additionally accepts address_id. Neither endpoint performs identity resolution or CRM eligibility filtering — that legacy behavior was retired.

Note

AI Implementation Hint

Prefer GET /contact_peer_events for new integrations. GET /contact_interactions remains available for existing callers but returns the same raw data — it is not a filtered/curated alternative.

Agent console equivalents

Agent-facing consoles use GET /service_agents/contact_interactions and GET /service_agents/contact_peer_events instead of the top-level paths documented on this page – see Agent Console for the authentication model shared by all /service_agents/* endpoints. The response shape is identical (TimelineManagerPeerEventListResponse), with two differences specific to the agent-console variant:

  • GET /service_agents/contact_interactions does not require a filter. If peer_type/peer_target, contact_id, and address_id are all omitted, it returns the full customer interaction history instead, scoped to a since lookback window (query parameter, default 30d, maximum 180d). The top-level GET /contact_interactions has no such fallback and requires exactly one filter.

  • GET /service_agents/contact_peer_events still requires exactly one of contact_id or peer_type``+``peer_target, matching the top-level GET /contact_peer_events behavior.

Filtering

Exactly one filter is required per request:

By Contact

GET https://api.voipbin.net/v1.0/contact_peer_events?contact_id=<contact_id>

Resolves every address registered to the contact and returns activity matching any of them.

By Peer Address

GET https://api.voipbin.net/v1.0/contact_peer_events?peer_type=tel&peer_target=%2B155****4567

Returns activity for a single address directly, without needing a resolved contact record. Useful for ad-hoc lookups of a specific phone number or email address.

Note

AI Implementation Hint

As with Contact lookups, URL-encode + as %2B in peer_target when the type is tel.

Note

Request vs. Response Shape

The filter query parameters (peer_type / peer_target) are two flat strings, but each returned row’s peer and local fields are full Address objects (type/target/target_name/name/detail) — the platform’s standard cross-service address shape, distinct from Contact’s Address structure. This is intentional: the query-string filter stays simple (matching how you already search Contact Interactions), while the response gives you the complete address record for display. See Structures for the full response field list.

Internal-Resource Noise

Because this endpoint applies no filtering, peer_type may be a value your application does not otherwise expect from customer-facing endpoints, such as:

peer_type

Description

tel

A phone number (customer-facing, same as Contact Interactions)

email

An email address (customer-facing, same as Contact Interactions)

agent

An internal agent extension leg

ai

An AI participant leg

conference

A conference bridge leg

sip

A raw SIP trunk leg

Applications displaying this data to end users are responsible for filtering or clearly labeling non-customer-facing rows themselves. This applies identically whether you call GET /contact_peer_events or the legacy GET /contact_interactions.

Pagination

Results are paginated with a cursor token, newest first.

GET https://api.voipbin.net/v1.0/contact_peer_events?peer_type=tel&peer_target=%2B155****4567&page_size=50
     |
     v
{ "result": [...], "next_page_token": "2026-01-15T10:30:00.123000Z" }
     |
     v
GET https://api.voipbin.net/v1.0/contact_peer_events?peer_type=tel&peer_target=%2B155****4567&page_size=50&page_token=2026-01-15T10:30:00.123000Z

Troubleshooting

  • 400 Bad Request when filtering:

    • Cause: Zero filters, or more than one filter (contact_id together with peer_type/peer_target), were provided.

    • Fix: Provide exactly one of contact_id or peer_type``+``peer_target.

  • Unexpected agent/ai/conference rows in results:

    • Cause: This is expected behavior — both Peer Events and (as of the Contact Interactions retirement) legacy Contact Interactions return raw, unfiltered activity by design.

    • Fix: Filter peer_type client-side; neither endpoint offers server-side CRM filtering anymore.

  • Empty result for a contact with known activity:

    • Cause: The contact has zero registered addresses, so there was nothing to search.

    • Fix: Verify the contact has addresses via GET /contacts/{id}.