Requests and responses when using the Pexip Infinity external policy API

Pexip Infinity accesses the external policy API via a GET request over HTTP or HTTPS to the appropriate external policy server URL (as configured in the policy profile).

We strongly recommend that you use HTTPS (not HTTP) in production environments.

A number of request parameters are added to the request URL according to the request type. This provides flexibility to the decision-making process within the policy server, and means, for example, that the policy server could return:

different media location information based on the remote_alias or the call protocol
a different avatar for the same participant based on the originally dialed local_alias or the service_name
a different set of directory contacts depending on the registered_alias making the request.

This topic contains a summary of the supported requests and response guidelines. Each request type is then explained in more detail (see service configuration, participant properties, media location, participant avatar, directory information and registration alias) including the parameters sent to the policy server for that request, the expected response and some examples. Finally, there is a summary matrix showing which parameters are contained in each policy request type.

Request types summary

The following table shows the different API request types that a Conferencing Node can send to an external policy server.

Policy request type	Description and request URI
Service configuration	Obtains the configuration details of a service. Pexip Infinity typically makes this request when it: receives an incoming call request needs to place a call to a given alias Request URI: <policy_server_uri>/policy/v1/service/configuration
Participant properties	This allows some of the participant's call properties, such as their display name or role, to be changed before they join the conference. This allows you, for example, to anonymize a participant's name or modify their role based on other properties of the call or their associated Identity Provider. For WebRTC participants it is applied after any PIN entry or SSO steps (and hence has access to Identity Provider attributes). For SIP/H.323 endpoints, it is applied before any PIN entry steps. Participant policy is applied after any service configuration policy, and before media location policy. Request URI: <policy_server_uri>/policy/v1/participant/properties
Media location	Obtains the system location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant. A media location request is often made after a service configuration data request (and after any participant policy). Request URI: <policy_server_uri>/policy/v1/participant/location
Participant avatar	Obtains the image to display to represent a conference participant or directory contact. Request URI: <policy_server_uri>/policy/v1/participant/avatar/<alias> where <alias>* is the alias of the participant/contact whose avatar is required.
Directory information	Obtains directory information — a list of device or VMR aliases and their associated names. This is used to provide phonebook information to Connect apps that are registered to a Pexip Infinity Conferencing Node. Request URI: <policy_server_uri>/policy/v1/registrations
Registration alias	Used to determine whether a device alias is allowed to register to a Conferencing Node. Request URI: <policy_server_uri>/policy/v1/registrations/<alias> where <alias>* is the alias of the device that is making the registration request.
* The alias may include scheme information, for example sip:alice@example.com. The policy server must be able to parse the received alias in an appropriate manner.

Note that:

You can configure whether specific request types are sent or not, on a per policy profile basis, via Call control > Policy Profiles. If a request type is disabled, Pexip Infinity will fall back to its own default behavior for that request type.
Pexip Infinity has a non-configurable timeout of 5 seconds for each attempt it makes to contact a policy server.
Most policy requests are sent from the Conferencing Node that is handling the call signaling or has received the registration request. However, requests are sent from the Conferencing Node that is handling the call media in the following situations:
- It is a participant avatar request.
- The participant is in a Virtual Reception (note that when the endpoint initially calls the Virtual Reception alias, the requests will come from the Conferencing Node handling the signaling — as usual, but after being placed into the Virtual Reception all subsequent requests i.e. when the participant enters the number of the VMR they want to join, are sent from the Conferencing Node that is handling the Virtual Reception call media).
You may see multiple service configuration, participant and media location requests when handling Connect app participants.

Policy server responses — general information

The policy server response to a request should be a 200 OK message. The response header must include the Content-Type, and the message body must include the requested content.

The response for all requests, except for participant avatar requests, must return a Content-Type of application/json. The policy server can return an error code e.g. 404 if it wants Pexip Infinity to fall back to its own default behavior for a specific request. Pexip Infinity will not follow any 301/302 redirects received from the policy server.

The response to a request takes the basic format:

{
"status": "success",
"action": "reject|redirect|continue",
"result": { <data> },
"<other_keys>": "<other_values>"
}

where:

if "status" is anything other than "success", the response is deemed to have failed and Pexip Infinity will fall back to its default behavior (which is to attempt to retrieve the relevant data from its own internal database), unless the "action" field is supported in the response for that request type, in which case the "action" field instructs Pexip Infinity how to proceed.
"action" is an optional value that may be included in responses to service configuration and registration alias requests. When present, it instructs Pexip Infinity how to proceed in failure scenarios:
- "reject" instructs Pexip Infinity to reject the request — for a service configuration or participant properties request this would mean to reject the call (i.e. return "conference not found"), and for a registration request it would mean to reject the registration. However, note that if you have local policy enabled for service configuration or participant properties, the local policy could change the action and provide updated service configuration / participant properties instead.
- "redirect" instructs Pexip Infinity to send a SIP response with status "302 redirect" to the requesting endpoint, telling it to place an otherwise identical call to a different alias. The "result" field specifies the alias to be used, using the format
  {"new_alias": "sip:alias@example.com"}
- "continue" (or any other value except "reject" or "redirect") instructs Pexip Infinity to fall back to its default behavior (which is to attempt to retrieve the service configuration or device alias data from its own internal database).
"result" is a JSON object of key value pairs as appropriate for the request type. The specific requirements of what must be included in the result is included below in the descriptions of each request type. The fields in the JSON object can be supplied in any order. All fields have a length limit of 250 characters.
"<other_keys>" and "<other_values>" can be zero, one or more optional key value pairs. If included, they do not affect how Pexip Infinity processes the response but they will be included in any associated support log messages. They could, for example, indicate the version number of the software running on the policy server, or contain "reason" information for failure responses.

Note that responses to participant avatar requests have different requirements (see Participant avatar response for details).

Dialing out from conference

Pexip Infinity makes a service configuration request if it dials out from a conference to invite a participant to join (where the call_direction parameter will be dial_out). In these cases, the response to the service configuration request must match the existing service data (i.e. the same name, service_type and so on).

When dialing out, the only configuration you can control via policy is:

The prefer_ipv6 setting in the service configuration response.
The media location — you can do this in the response to the media location request that follows the service configuration request.

Service configuration requests

Obtains the configuration details of a service. Pexip Infinity typically makes this request when it:

receives an incoming call request
needs to place a call to a given alias

Request URI: <policy_server_uri>/policy/v1/service/configuration

Pexip Infinity includes the following fields in a service configuration request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call. It is present on both inbound and outbound call requests but is meaningful only for inbound calls.
breakout_uuid	The uuid of a breakout room (if applicable).
call_direction	The direction of the call that triggered the request. Values can be: "dial_in": calls in to Pexip Infinity "dial_out": calls dialed out from Pexip Infinity "non_dial": when policy is triggered by other requests that are not related to incoming or outgoing call setup, such as when an H.323 LRQ or a SIP SUBSCRIBE or OPTIONS request is received.
call_tag	An optional call tag that is assigned to a participant.
display_count	When included in participant configuration it is the number of screens possessed by the endpoint, if known. This could be either the display count signaled by the endpoint, or as defined by the theme's vendordata.json file. When included in service configuration it is the number of screens signaled by a Microsoft Teams Room when joining via One-Touch Join.
has_authenticated_display_name	Boolean indicating if the participant's display name was provided and authenticated by an Identity Provider.
idp_uuid	The UUID of the Identity Provider who provided and authenticated the participant's display name, and provided any idp_attributes in participant policy.
local_alias	In the context of service and participant configuration requests, this is the incoming alias (typically the alias that the endpoint has dialed). This is the primary item of information that the policy server will use to return appropriate service configuration data.
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip	The IP address of the Conferencing Node making the request.
p_Asserted-Identity †	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323", "teams" or "mssip". (Note that the protocol is always reported as "api" when a Connect app dials in to Pexip Infinity.)
pseudo_version_id	The Pexip Infinity software build number.
registered	Boolean indicating whether the remote participant is registered or not.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
service_name ‡	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag ††	The service tag associated with the service_name parameter.
supports_direct_media	Boolean indicating if the service supports direct media or not.
teams_tenant_id	Contains the Microsoft Teams tenant ID on an inbound Teams call to Pexip Infinity for Teams Rooms SIP/H.323 calling.
telehealth_request_id ◊	The telehealth call id.
third_party_passcode	The passcode field provided by the Microsoft Teams Room calendaring service*, extracted from the meeting invitation.
trigger	The trigger for the policy request. Values: "web", "web_avatar_fetch", "invite", "options", "subscribe", "setup", "arq", "lrq", "two_stage_dialing", "teams", or "unspecified".
unique_service_name ‡	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id	The Pexip Infinity software version number.
† Only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header. Note that the ms_subnet and p_asserted_identity fields use only underscores and lower case characters in their names when used in local policy (normally they are referenced as ms-subnet and p_Asserted-Identity). ‡ Only included in outbound call requests and for breakout rooms. †† Only included in outbound call requests. ◊ Only included in Epic telehealth calls.

This example shows a GET request for service configuration data when alice@example.com has dialed meet.bob from a SIP endpoint:

GET /example.com/policy/v1/service/configuration?call_direction=dial_in&protocol=sip&bandwidth=0&vendor=Cisco/CE&encryption=On&registered=False&trigger=invite&remote_display_name=Alice&remote_alias=sip:alice@example.com&remote_address=10.44.151.5&remote_port=58435&call_tag=&idp_uuid=&has_authenticated_display_name=False&supports_direct_media=False&teams_tenant_id=&location=London&node_ip=10.144.101.21&version_id=35&pseudo_version_id=77683.0.0&local_alias=meet.bob"

Response to a service configuration request

The response to a service configuration request takes the basic format:

{
"status": "success",
"action": "reject|redirect|continue",
"result": { <service_configuration_data> }
}

where:

"action" is an optional value that, when included, instructs Pexip Infinity how to proceed in failure scenarios:
- "reject" instructs Pexip Infinity to reject the call (i.e. return "conference not found"). However, note that if you have local policy enabled for service configuration, the local policy could still provide some service configuration instead.
- "redirect" instructs Pexip Infinity to send a SIP response with status "302 redirect" to the requesting endpoint, telling it to place an otherwise identical call to a different alias. The "result" field specifies the alias to be used, using the format
  {"new_alias": "sip:alias@example.com"}
- "continue" instructs Pexip Infinity to fall back to its default behavior (which is to attempt to retrieve the service configuration data from its own internal database).
"result" is a JSON object of multiple key value pairs that describes the service:
- Some data fields are required, and some are optional: the fields expected by Pexip Infinity in the response depend upon the returned service_type — either "conference" or "lecture" for a Virtual Meeting Room or Virtual Auditorium, "gateway" for an Infinity Gateway call, "two_stage_dialing" for a Virtual Reception, "media_playback" for a Media Playback Service, or "test_call" for a Test Call Service.
- Note that the response configures the service and therefore each request for the same service should return the same configuration for that service. The only fields that can return a different value (per participant) are the Identity Provider, PIN and bandwidth related fields (guest_identity_provider_group, host_identity_provider_group, pin, guest_pin, max_callrate_in, max_callrate_out). However, you can also use participant policy to change some of the properties of a participant calling into that service, such as their display name.
the "action" field is ignored if "status" is "success" and "result" contains valid data (and it is a 200 OK message).

The fields expected in the response for each service type are described below:

Virtual Meeting Room / Virtual Auditorium service types response fields

Pexip Infinity expects the following fields to be returned for a service_type of "conference" (VMR) or "lecture" (Virtual Auditorium):

Field name	Required	Type	Description
name	Yes	String	The name of the service. You could, for example, use the local_alias received in the configuration request. Pexip Infinity will then use this name — as the service_name parameter — in subsequent requests to identify that service. If this configuration is defining a breakout room, then this is the name of the main VMR.
service_tag	Yes	String	A unique identifier used to track usage of this service.
service_type	Yes	String	The type of service, in this case: "conference": a Virtual Meeting Room, or "lecture": a Virtual Auditorium
allow_guests	No	Boolean	Whether to distinguish between Host and Guest participants: true: the conference has two types of participants: Hosts and Guests. The pin to be used by Hosts must be specified. A guest_pin can optionally be specified; if a guest_pin is not specified, Guests can join without a PIN. false: all participants have Host privileges Default: false
automatic_participants	No	List	A list of participants to dial automatically when the conference starts. Each participant in the list contains a number of fields as described in Automatically dialed participants (ADP) fields.
breakout_rooms	No	Boolean	Whether Breakout Rooms are enabled for the conference. See Breakout room fields below for configuration for a breakout room. Default: false
bypass_proxy	No	Boolean	Whether to bypass a Proxying Edge Node and send media directly to a Transcoding Conferencing Node. true: if the call signaling is received by a Proxying Edge Node, that proxying node will determine which Transcoding Conferencing Node should handle the call media (as per standard media allocation rules), but it then instructs the client to send its media directly to that nominated transcoding node, thus bypassing the proxying node. The proxying node will continue to handle the call signaling. false: standard behavior — normal proxying and media allocation rules apply. Default: false
call_type	No	String	The call capability of the conference. It can be limited to: "video": main video plus presentation "video-only": main video only "audio": audio-only Default: "video"
crypto_mode	No	String	Controls the media encryption requirements for participants connecting to this service. <null>: use the global media encryption setting. "besteffort": each participant will use media encryption if their device supports it, otherwise the connection will be unencrypted. "on": all participants (including RTMP participants) must use media encryption. "off": all H.323, SIP and MS-SIP participants must use unencrypted media. (RTMP participants will use encryption if their device supports it, otherwise the connection will be unencrypted.) Default: <null> (use global setting)
description	No	String	A description of the service.
direct_media	No	String	Allows this VMR to use direct media between participants. When enabled, the VMR provides non-transcoded, encrypted, point-to-point calls between any two WebRTC participants. The options are: "best_effort": use direct media in this VMR where possible (when there are two WebRTC participants only), otherwise use standard, transcoded media connections via a Conferencing Node. "always": allow direct media calls only — this limits all calls in this VMR to two WebRTC participants. "never": do not use direct media in this VMR. Default: "never" Note that direct media is not supported if breakout rooms are also enabled for this VMR.
direct_media_notification_duration	No	Integer	The number of seconds to show a notification to participants before being escalated into a transcoded call, or de-escalated into a direct media call. Range: 0 to 30 seconds. Default: 0 seconds
enable_chat	No	String	Whether chat messaging is enabled for the conference: "default": as per the global configuration setting "yes": chat is enabled "no": chat is disabled Default: "default"
enable_active_speaker_indication	No	Boolean	When active speaker display is enabled, the display name or alias of the current speaker is shown across the bottom of their video image. true: active speaker is indicated false: active speaker is not indicated Default: false
enable_overlay_text	No	Boolean	If participant name overlays are enabled, the display names or aliases of all participants are shown in a text overlay along the bottom of their video image. For more information, see Showing the names of active speakers and participants. true: participant names are shown false: participant names are not shown Default: false
force_presenter_into_main (applies to service_type of "lecture" only)	No	Boolean	Controls whether the Host who is presenting is locked into the main video position: true: the Host sending the presentation stream will always hold the main video position false: the main video position is voice-switched Default: false
guest_pin	No	String	Guest PIN — the secure access code for Guest participants.
guest_view (applies to service_type of "lecture" only)	No	String	The layout seen by Guests: "one_main_zero_pips": full-screen main speaker only "one_main_seven_pips": large main speaker and up to 7 other participants "one_main_twentyone_pips": main speaker and up to 21 other participants "two_mains_twentyone_pips": 2 main speakers and up to 21 other participants "one_main_thirtythree_pips": 1 small main speaker and up to 33 other participants "four_mains_zero_pips": 2 x 2 layout, up to a maximum of 4 speakers "nine_mains_zero_pips": 3 x 3 layout, up to a maximum of 9 speakers "sixteen_mains_zero_pips": 4 x 4 layout, up to a maximum of 16 speakers "twentyfive_mains_zero_pips": 5 x 5 layout, up to a maximum of 25 speakers "five_mains_seven_pips": Adaptive Composition layout (you must also set Host view to Adaptive Composition) "one_main_one_pip": large main speaker with one overlaying participant "one_main_nine_around": one main speaker and up to 9 other participants "one_main_twelve_around": large main speaker and up to 12 other participants "two_mains_eight_around": two main speakers and up to 8 other participants Default: "one_main_seven_pips" Only Hosts are displayed. Guests can hear but not see any of the other Guests.
guests_can_present	No	Boolean	Controls whether the Guests in the conference are allowed to present content. true: Guests and Hosts can present into the conference false: only Hosts can present Default: true
guests_can_see_guests	No	String	Controls whether Guests see other Guests during a conference. This applies to Virtual Auditoriums only. no_hosts: Guests see other guests only if no other Hosts are present. always: Guests are always shown to other Guests (if there is space in the layout after hosts). never: Guests never see other Guests. Note that: When no Hosts are present and Guests do not see other Guests, they see a "Welcome to the lobby" splash screen (the theme screen key is inlobby). This does not effect the behavior at the start of a meeting — Guests always still see the "Waiting for the host" screen. The Guests-only timeout setting still applies and will end the meeting for everybody after the configured timeout period. However, if Guests are sent to a breakout room and there are no Hosts present in the breakout room then it does apply immediately — Guests are shown the "Welcome to the lobby" splash screen until a Host joins the breakout room, and Guests will only see Hosts (as usual for a Virtual Auditorium). Default: no_hosts
guest_identity_provider_group	No	String	The set of Identity Providers to be offered to Guests to authenticate with, in order to use the service. If this is blank, Guests are not required to authenticate. For more information, see About participant authentication.
host_identity_provider_group	No	String	The set of Identity Providers to be offered to Hosts to authenticate with, in order to use the service. If this is blank, Hosts are not required to authenticate. For more information, see see About participant authentication.
host_view (applies to service_type of "lecture" only)	No	String	The layout seen by Hosts: "one_main_zero_pips": full-screen main speaker only "one_main_seven_pips": large main speaker and up to 7 other participants "one_main_twentyone_pips": main speaker and up to 21 other participants "two_mains_twentyone_pips": 2 main speakers and up to 21 other participants "one_main_thirtythree_pips": 1 small main speaker and up to 33 other participants "four_mains_zero_pips": 2 x 2 layout, up to a maximum of 4 speakers "nine_mains_zero_pips": 3 x 3 layout, up to a maximum of 9 speakers "sixteen_mains_zero_pips": 4 x 4 layout, up to a maximum of 16 speakers "twentyfive_mains_zero_pips": 5 x 5 layout, up to a maximum of 25 speakers "five_mains_seven_pips": Adaptive Composition layout "one_main_one_pip": large main speaker with one overlaying participant "one_main_nine_around": one main speaker and up to 9 other participants "one_main_twelve_around": large main speaker and up to 12 other participants "two_mains_eight_around": two main speakers and up to 8 other participants "teams": Teams-like layout (this is only suitable for use with Microsoft Teams gateway calls) Default: "one_main_seven_pips"
ivr_theme_name	No	String	The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
live_captions_enabled	No	String	When enabled, participants using the Connect web app are given the option to turn on the live captions for conferences using this service. "default": as per global configuration setting. "yes": live captions may be enabled. "no": live captions cannot be enabled. Default: "default"
live_captions_language	No	String	The language in which live captions are displayed. For AIMS v1.0, if set this must be the same as the source_language.
local_display_name	No	String	The display name of the calling alias.
locked	No	Boolean	Whether to lock the conference on creation: true: the conference will be locked on creation false: the conference will not be locked Note that this field has no effect on the conference if it is already running. Default: false
max_callrate_in	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_callrate_out	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_pixels_per_second	No	String	Controls the maximum call quality for participants connecting to this service: <null>: use the global maximum call quality setting. "sd": each participant is limited to SD quality. "hd": each participant is limited to HD (720p) quality. "fullhd": allows any endpoint capable of Full HD to send and receive its main video at 1080p. Default: <null> (use global setting) See Setting and limiting call quality for more information.
mute_all_guests	No	Boolean	Controls whether to mute guests when they first join the conference: true: mute Guests when they first join the conference false: do not mute Guests when they first join the conference Default: false
non_idp_participants	No	String	Determines whether participants joining a SSO-protected service from devices other than the Connect web app (for example SIP or H.323 endpoints) are allowed to dial in to the service. "disallow_all": these devices are placed in a waiting room where they must wait to be admitted by a Host. "allow_if_trusted": these devices may join the service if they are locally registered. They must still enter a Host PIN or Guest PIN if either is required. All other devices are placed in a waiting room where they must wait to be admitted by a Host. For more information, see About participant authentication. Default: "disallow_all"
participant_limit	No	Integer	The maximum number of participants allowed to join the service.
pin	No	String	Host PIN — the secure access code for Host participants.
pinning_config	No	String	The name of the pinning configuration to apply (from the theme associated with the conference).
prefer_ipv6	No	String	Whether to use IPv6 for SIP media when dialing out to any ADPs: "default": use default Pexip Infinity behavior, which is to prefer IPv4 addresses for SIP media "yes": use IPv6 addresses for SIP media "no": do not use IPv6 addresses for SIP media Default: "default"
primary_owner_email_address	No	String	The email address of the owner of the VMR.
source_language	No	String	The language of the audio stream used by AIMS to generate live captions.
view (applies to service_type of "conference" only)	No	String	The layout seen by all participants: "one_main_zero_pips": full-screen main speaker only "one_main_seven_pips": large main speaker and up to 7 other participants "one_main_twentyone_pips": main speaker and up to 21 other participants "two_mains_twentyone_pips": 2 main speakers and up to 21 other participants "one_main_thirtythree_pips": 1 small main speaker and up to 33 other participants "four_mains_zero_pips": 2 x 2 layout, up to a maximum of 4 speakers "nine_mains_zero_pips": 3 x 3 layout, up to a maximum of 9 speakers "sixteen_mains_zero_pips": 4 x 4 layout, up to a maximum of 16 speakers "twentyfive_mains_zero_pips": 5 x 5 layout, up to a maximum of 25 speakers "five_mains_seven_pips": Adaptive Composition layout "one_main_one_pip": large main speaker with one overlaying participant "one_main_nine_around": one main speaker and up to 9 other participants "one_main_twelve_around": large main speaker and up to 12 other participants "two_mains_eight_around": two main speakers and up to 8 other participants "teams": Teams-like layout (this is only suitable for use with Microsoft Teams gateway calls) Default: "one_main_seven_pips"

Breakout room fields

If you want the configuration to represent a breakout room, then the following fields should also be supplied:

Field name	Required	Type	Description
breakout	Yes	Boolean	Indicates this is a breakout room. If breakout is true, then breakout_rooms should be false (you cannot create breakout rooms from within a breakout room). Also, note that name should be the main VMR room name (of which this is a breakout).
breakout_uuid	Yes	String	A uuid string that represents this breakout room, in the format “XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”.
breakout_name	Yes	String	Name of the breakout room.
breakout_uuids	No	List	When returning the main room configuration back to a Host you can include a list of uuid strings that represents multiple breakout rooms to be created. This causes the Host to attempt to join each of these breakout_uuid rooms as a control only participant. This will trigger another policy lookup that includes the following fields (either as external policy parameters, or as part of the call_info structure for internal policy): "service_name": "<main_room_name>_breakout_<breakout_uuid>" "unique_service_name": same as service_name "breakout_uuid": breakout_uuid of breakout room being created The response to these policy lookups should be a configuration block which represents a breakout room with the fields configured appropriately for each room.
breakout_description	No	String	Long name / description of the breakout room.
breakout_guests_allowed_to_leave	No	Boolean	Specifies if participants are given an option to leave the breakout room and return to the main room. Default: false
end_action	No	String	What to do with participants when the timer expires, or the breakout is closed: "disconnect": disconnect them all "transfer": transfer them back to the main room Default: "transfer"
end_time	No	Integer	Time when breakout ends, in seconds since epoch. 0 = no automatic end. Default: 0

See Route incoming calls directly into a breakout room for an example local policy script that shows how you could use these fields.

Infinity Gateway service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "gateway":

Field name	Required	Type	Description
local_alias	Yes	String	The calling or "from" alias. This is the alias that the recipient would use to return the call.
name	Yes	String	The name of the service. Ensure that all gateway service instances have a unique name to avoid conflicts between calls. Pexip Infinity will then use this name — as the service_name parameter — in subsequent requests to identify that call.
outgoing_protocol	Yes	String	The protocol to use to place the outgoing call: "h323": an H.323 call; you can also optionally nominate an h323_gatekeeper_name "sip": a SIP call; you can also optionally nominate a sip_proxy_name "mssip": a Microsoft Skype for Business / Lync call; you can also optionally nominate an mssip_proxy_name and a turn_server_name "rtmp": uses the RTMP protocol; typically this is used for content streaming "gms": for calls to the Google Meet service. "teams": for calls to the Microsoft Teams service.
remote_alias	Yes	String	The alias of the endpoint to call. The alias can include scheme information, for example sip:alice@example.com, but the call will always be made using the specified outgoing_protocol.
service_tag	Yes	String	A unique identifier used to track usage of this service.
service_type	Yes	String	The type of service, in this case: "gateway": an Infinity Gateway call
bypass_proxy	No	Boolean	Whether to bypass a Proxying Edge Node and send media directly to a Transcoding Conferencing Node. true: if the call signaling is received by a Proxying Edge Node, that proxying node will determine which Transcoding Conferencing Node should handle the call media (as per standard media allocation rules), but it then instructs the client to send its media directly to that nominated transcoding node, thus bypassing the proxying node. The proxying node will continue to handle the call signaling. false: standard behavior — normal proxying and media allocation rules apply. Default: false
call_type	No	String	The call capability of the outbound call: "video": main video plus presentation "video-only": main video only "audio": audio-only "auto": match the capability of the outbound call to that of the inbound call Default: "video"
crypto_mode	No	String	Controls the media encryption requirements for participants connecting to this service. <null>: use the global media encryption setting. "besteffort": each participant will use media encryption if their device supports it, otherwise the connection will be unencrypted. "on": all participants (including RTMP participants) must use media encryption. "off": all H.323, SIP and MS-SIP participants must use unencrypted media. (RTMP participants will use encryption if their device supports it, otherwise the connection will be unencrypted.) Default: <null> (use global setting)
called_device_type	No	String	The device or system to which to route the call: "external": route the call to a matching registered device if it is currently registered, otherwise attempt to route the call via an external system "registration": route the call to a matching registered device only (providing it is currently registered) "mssip_conference_id": route the call via a Skype for Business / Lync server to a SfB/Lync meeting where the remote_alias is a SfB/Lync meeting Conference ID "mssip_server": route the call via a Skype for Business / Lync server to a SfB/Lync client or meeting "gms_conference": for calls to the Google Meet service. "teams_conference": for calls to the Microsoft Teams service. "teams_user": for direct calls to a Microsoft Teams Room. "telehealth_profile": for calls to an Epic telehealth system. Default: "external"
denoise_audio	No	Boolean	Applies to Google Meet integrations only. Controls whether to remove background noise from audio streams as they pass through the infrastructure. Default: true
description	No	String	A description of the service.
dtmf_sequence	No	String	An optional DTMF sequence to transmit after the call to the dialed participant starts.
enable_active_speaker_indication	No	Boolean	When active speaker display is enabled, the display name or alias of the current speaker is shown across the bottom of their video image. true: active speaker is indicated false: active speaker is not indicated Default: false
enable_overlay_text	No	Boolean	If participant name overlays are enabled, the display names or aliases of all participants are shown in a text overlay along the bottom of their video image. For more information, see Showing the names of active speakers and participants. true: participant names are shown false: participant names are not shown Default: false
external_participant_avatar_lookup	No	String	Applies to Microsoft Teams integrations only. This determines whether or not the Teams Connector requests from Exchange Online an avatar for each participant in the Teams conference. "default": use the global external participant avatar lookup setting. "yes": request the participant avatar from Exchange Online via the Teams Connector. "no": use default avatar behavior. Default: "default" (use global setting)
gms_access_token_name	No	String	The name of the access token to use to resolve Google Meet IDs. You should select either a trusted or untrusted type of token, depending on whether you want to enable the device to be automatically admitted into the Google Meet conference (subject to also being a trusted endpoint from Pexip Infinity's perspective i.e. if the rule also has treat_as_trusted enabled). See Enabling access and admitting external participants into Google Meet conferences for more information.
h323_gatekeeper_name	No	String	The name* of the H.323 gatekeeper to use to place the outgoing call. DNS is used if no gatekeeper is specified.
ivr_theme_name	No	String	The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
live_captions_enabled	No	String	When enabled, participants using the Connect web app are given the option to turn on the live captions for conferences using this service. "default": as per global configuration setting. "yes": live captions may be enabled. "no": live captions cannot be enabled. Default: "default"
live_captions_language	No	String	The language in which live captions are displayed. For AIMS v1.0, if set this must be the same as the source_language.
local_display_name	No	String	The display name of the calling alias.
max_callrate_in	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_callrate_out	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_pixels_per_second	No	String	Controls the maximum call quality for participants connecting to this service: <null>: use the global maximum call quality setting. "sd": each participant is limited to SD quality. "hd": each participant is limited to HD (720p) quality. "fullhd": allows any endpoint capable of Full HD to send and receive its main video at 1080p. Default: <null> (use global setting) See Setting and limiting call quality for more information.
mssip_proxy_name	No	String	The name* of the Skype for Business / Lync server to use to place the outgoing call. DNS is used if no server is specified.
outgoing_location_name	No	String	The name* of the location of a Conferencing Node from which to place the call.
prefer_ipv6	No	String	Whether to use IPv6 for SIP media for the outgoing call: "default": use default Pexip Infinity behavior, which is to prefer IPv4 addresses for SIP media "yes": use IPv6 addresses for SIP media "no": do not use IPv6 addresses for SIP media Default: "default"
sip_proxy_name	No	String	The name* of the SIP proxy to use to place the outgoing call. DNS is used if no proxy is specified.
source_language	No	String	The language of the audio stream used by AIMS to generate live captions.
stun_server_name	No	String	The name* of the STUN server to use when placing calls to external SIP and WebRTC endpoints that are ICE-enabled (such as Skype for Business / Lync clients and Connect app WebRTC clients).
teams_fit_to_frame	No	String	Applies to Microsoft Teams calls only. Determines whether or not ("yes" or "no") to enable the "Fit to frame" option within Teams for this VTC participant. Default: "no"
teams_proxy_name	No	String	The name of the Teams Connector to handle the call to Microsoft Teams. If you do not specify anything, the Teams Connector associated with the outgoing location is used.
treat_as_trusted	No	Boolean	This indicates that the target of this Call Routing Rule may treat the caller as part of the target organization for trust purposes.
turn_server_name	No	String	The name* of the TURN server to offer to external SIP and WebRTC endpoints that are ICE-enabled (such as Skype for Business / Lync clients and Connect app WebRTC clients).
view	No	String	The layout seen by Pexip participants: "one_main_zero_pips": full-screen main speaker only "one_main_seven_pips": large main speaker and up to 7 other participants "one_main_twentyone_pips": main speaker and up to 21 other participants "two_mains_twentyone_pips": 2 main speakers and up to 21 other participants "one_main_thirtythree_pips": 1 small main speaker and up to 33 other participants "four_mains_zero_pips": 2 x 2 layout, up to a maximum of 4 speakers "nine_mains_zero_pips": 3 x 3 layout, up to a maximum of 9 speakers "sixteen_mains_zero_pips": 4 x 4 layout, up to a maximum of 16 speakers "twentyfive_mains_zero_pips": 5 x 5 layout, up to a maximum of 25 speakers "five_mains_seven_pips": Adaptive Composition layout "one_main_one_pip": large main speaker with one overlaying participant "one_main_nine_around": one main speaker and up to 9 other participants "one_main_twelve_around": large main speaker and up to 12 other participants "two_mains_eight_around": two main speakers and up to 8 other participants "teams": Teams-like layout (this is only suitable for use with Microsoft Teams gateway calls) Default: "one_main_seven_pips"
* The returned "name" must match the name of the location, H.323 gatekeeper, SIP proxy etc. configured within Pexip Infinity.

Virtual Reception service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "two_stage_dialing" (Virtual Reception):

Field name	Required	Type	Description
name	Yes	String	The name of the service. You could, for example, use the local_alias received in the configuration request. Pexip Infinity will then use this name — as the service_name parameter — in subsequent requests to identify that service.
service_tag	Yes	String	A unique identifier used to track usage of this service.
service_type	Yes	String	The type of service, in this case: "two_stage_dialing": a Virtual Reception
bypass_proxy	No	Boolean	Whether to bypass a Proxying Edge Node and send media directly to a Transcoding Conferencing Node. true: if the call signaling is received by a Proxying Edge Node, that proxying node will determine which Transcoding Conferencing Node should handle the call media (as per standard media allocation rules), but it then instructs the client to send its media directly to that nominated transcoding node, thus bypassing the proxying node. The proxying node will continue to handle the call signaling. false: standard behavior — normal proxying and media allocation rules apply. Default: false
call_type	No	String	The call capability of the reception. It can be limited to: "video": main video plus presentation "video-only": main video only "audio": audio-only Default: "video"
crypto_mode	No	String	Controls the media encryption requirements for participants connecting to this service. <null>: use the global media encryption setting. "besteffort": each participant will use media encryption if their device supports it, otherwise the connection will be unencrypted. "on": all participants (including RTMP participants) must use media encryption. "off": all H.323, SIP and MS-SIP participants must use unencrypted media. (RTMP participants will use encryption if their device supports it, otherwise the connection will be unencrypted.) Default: <null> (use global setting)
description	No	String	A description of the service.
gms_access_token_name	No	String	The name of the access token to use to resolve Google Meet IDs. When configuring a Virtual Reception it does not matter if you use a trusted or untrusted access token.
ivr_theme_name	No	String	The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
local_display_name	No	String	The display name of the calling alias.
match_string	No	String	An optional regular expression used to match against the alias entered by the caller into the Virtual Reception. If the entered alias does not match the expression, the Virtual Reception will not route the call. If this field is left blank, any entered alias is permitted. For more information, see Restricting or transforming the aliases entered into a Virtual Reception.
max_callrate_in	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_callrate_out	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_pixels_per_second	No	String	Controls the maximum call quality for participants connecting to this service: <null>: use the global maximum call quality setting. "sd": each participant is limited to SD quality. "hd": each participant is limited to HD (720p) quality. "fullhd": allows any endpoint capable of Full HD to send and receive its main video at 1080p. Default: <null> (use global setting) See Setting and limiting call quality for more information.
mssip_proxy_name	No	String	The name of the Skype for Business / Lync server to use to resolve the SfB/Lync Conference ID entered by the user in the Virtual Reception.
post_match_string	No	String	An optional regular expression used to match against the meeting code entered by the caller into the Virtual Reception. This is typically used in conjunction with the post_replace_string to transform the meeting code into a distinct alias pattern that will match a Call Routing Rule configured to route calls into external conferences. For example, you would typically set the regex match to (.*) (to match everything) and the replace string pattern to something like meet.\1 which would prefix the meeting code entered into the Virtual Reception with "meet.". You would then configure an associated Call Routing Rule to match calls placed to aliases prefixed with meet. which then strips off that prefix (to leave just the meeting code again) before directing the call to the external conference.
post_replace_string	No	String	An optional regular expression used in conjunction with the post_match_string field to transform the meeting code into a distinct alias pattern that will match a Call Routing Rule configured to route calls into external conferences. (Only applies if the post-lookup regex match string is also configured and the entered code matches that regex.)
replace_string	No	String	An optional regular expression used to transform the alias entered by the caller into the Virtual Reception. (Only applies if a regex match string is also configured and the entered alias matches that regex.) Leave this field blank if you do not want to change the alias entered by the caller.
system_location_name	No	String	This is an optional field used in conjunction with the two_stage_dial_type setting, when a type other than regular is selected. If specified, a Conferencing Node in this system location will perform the SfB/Lync Conference ID lookup on the SfB/Lync server, or the Microsoft Teams or Google Meet code lookup, as appropriate. We recommend that a location is specified here, otherwise the transcoding node hosting the Virtual Reception will perform the lookup (which may lead to routability issues).
teams_proxy_name	No	String	The name of the Teams Connector to use to resolve Microsoft Teams meeting codes entered in a Virtual Reception. If you do not specify anything, the Teams Connector associated with the outgoing location is used.
two_stage_dial_type	No	String	The type of Virtual Reception: "regular": the default type of Virtual Reception, used for routing calls to VMRs, or to other devices and call control systems via the Infinity Gateway. For information on how to use this option to enable telephone access to VMRs, see Integrating with telephone systems (PSTN). "mssip": a special type of Virtual Reception, used when you want to provide an IVR gateway to scheduled and ad hoc Skype for Business / Lync meetings. See Configuring Pexip Infinity as a Skype for Business / Lync gateway for more information. "gms": a special type of Virtual Reception, used when you want to provide an IVR gateway to scheduled and ad hoc Google Meet meetings. See Integrating Google Meet with Pexip Infinity for more information. "teams": a special type of Virtual Reception, used when you want to provide an IVR gateway to scheduled and ad hoc Microsoft Teams meetings. See Integrating Microsoft Teams with Pexip Infinity for more information. Default: "regular"

Media Playback Service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "media_playback" (Media Playback Service):

Field name	Required	Type	Description
name	Yes	String	The name of the service. You could, for example, use the local_alias received in the configuration request. Pexip Infinity will then use this name — as the service_name parameter — in subsequent requests to identify that service.
media_playlist_name	Yes	String	The name of the media playlist.
service_type	Yes	String	The type of service, in this case: "media_playback": a Media Playback Service
service_tag	Yes	String	A unique identifier used to track usage of this service.
allow_guests	No	Boolean	Whether to distinguish between Host and Guest participants: true: the conference has two types of participants: Hosts and Guests. The pin to be used by Hosts must be specified. A guest_pin can optionally be specified; if a guest_pin is not specified, Guests can join without a PIN. false: all participants have Host privileges Default: false
description	No	String	A description of the service.
guest_pin	No	String	Guest PIN — the secure access code for Guest participants.
guest_identity_provider_group	No	String	The set of Identity Providers to be offered to Guests to authenticate with, in order to use the service. If this is blank, Guests are not required to authenticate. For more information, see About participant authentication.
host_identity_provider_group	No	String	The set of Identity Providers to be offered to Hosts to authenticate with, in order to use the service. If this is blank, Hosts are not required to authenticate. For more information, see see About participant authentication.
ivr_theme_name	No	String	The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
max_callrate_in	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_callrate_out	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will send to each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_pixels_per_second	No	String	Controls the maximum call quality for participants connecting to this service: <null>: use the global maximum call quality setting. "sd": each participant is limited to SD quality. "hd": each participant is limited to HD (720p) quality. "fullhd": allows any endpoint capable of Full HD to send and receive its main video at 1080p. Default: <null> (use global setting) See Setting and limiting call quality for more information.
non_idp_participants	No	String	Determines whether participants joining a SSO-protected service from devices other than the Connect web app (for example SIP or H.323 endpoints) are allowed to dial in to the service. "disallow_all": these devices are placed in a waiting room where they must wait to be admitted by a Host. "allow_if_trusted": these devices may join the service if they are locally registered. They must still enter a Host PIN or Guest PIN if either is required. All other devices are placed in a waiting room where they must wait to be admitted by a Host. For more information, see About participant authentication. Default: "disallow_all"
on_completion	No	String	Action to perform on playlist completion. This is defined as a jSON object. To disconnect the user, use the syntax: "on_completion": {"disconnect": true } To perform a transfer, use the syntax: "on_completion": {"transfer": {"conference": "<alias>"}} or (if you also want to specify the role): "on_completion": {"transfer": {"conference": "<alias>", "role": "<role>" }}
pin	No	String	Host PIN — the secure access code for Host participants.

Test Call Service type response fields

Pexip Infinity expects the following fields to be returned for a service_type of "test_call" (Test Call Service):

Field name	Required	Type	Description
name	Yes	String	The name of the service. You could, for example, use the local_alias received in the configuration request. Pexip Infinity will then use this name — as the service_name parameter — in subsequent requests to identify that service.
service_tag	Yes	String	A unique identifier used to track usage of this service.
service_type	Yes	String	The type of service, in this case: "test_call": a Test Call Service
bypass_proxy	No	Boolean	Whether to bypass a Proxying Edge Node and send media directly to a Transcoding Conferencing Node. true: if the call signaling is received by a Proxying Edge Node, that proxying node will determine which Transcoding Conferencing Node should handle the call media (as per standard media allocation rules), but it then instructs the client to send its media directly to that nominated transcoding node, thus bypassing the proxying node. The proxying node will continue to handle the call signaling. false: standard behavior — normal proxying and media allocation rules apply. Default: false
call_type	No	String	The call capability of the service. It can be limited to: "video": main video plus presentation "video-only": main video only "audio": audio-only Default: "video"
crypto_mode	No	String	Controls the media encryption requirements for participants connecting to this service. <null>: use the global media encryption setting. "besteffort": each participant will use media encryption if their device supports it, otherwise the connection will be unencrypted. "on": all participants (including RTMP participants) must use media encryption. "off": all H.323, SIP and MS-SIP participants must use unencrypted media. (RTMP participants will use encryption if their device supports it, otherwise the connection will be unencrypted.) Default: <null> (use global setting)
description	No	String	A description of the service.
ivr_theme_name	No	String	The name of the theme to use with the service. If no theme is specified, the default Pexip theme is used.
local_display_name	No	String	The display name of the calling alias.
max_callrate_in	No	Integer	The maximum media bandwidth in bps that Pexip Infinity will receive from each individual participant dialed in to the service. Range 128000 to 8192000 bps.
max_pixels_per_second	No	String	Controls the maximum call quality for participants connecting to this service: <null>: use the global maximum call quality setting. "sd": each participant is limited to SD quality. "hd": each participant is limited to HD (720p) quality. "fullhd": allows any endpoint capable of Full HD to send and receive its main video at 1080p. Default: <null> (use global setting) See Setting and limiting call quality for more information.

Automatically dialed participants (ADP) fields

The automatic_participants list field, which may be included in the service configuration response for a service_type of "conference" (VMR) or "lecture" (Virtual Auditorium), contains the following fields per participant:

Field name	Required	Type	Description
local_alias	Yes	String	The calling or "from" alias. This is the alias that the recipient would use to return the call.
protocol	Yes	String	The protocol to use to place the outgoing call: "h323": an H.323 call "sip": a SIP call "mssip": a Microsoft Skype for Business / Lync call "rtmp": uses the RTMP protocol; typically this is used for content streaming Calls are routed to externally-located participants based on the configuration of the system location used to place the call.
remote_alias	Yes	String	The alias of the endpoint to call.
role	Yes	String	The level of privileges the participant has in the conference: "chair": the participant has Host privileges "guest": the participant has Guest privileges
call_type	No	String	The call capability of the participant. It can be limited to: "video": main video plus presentation "video-only": main video only "audio": audio-only Default: "video"
dtmf_sequence	No	String	An optional DTMF sequence to transmit after the call to the dialed participant starts.
keep_conference_alive	No	String	Determines whether the conference continues when all other non-ADP participants have disconnected: "keep_conference_alive": the conference continues to run until this participant disconnects (applies to Hosts only). "keep_conference_alive_if_multiple": the conference continues to run as long as there are two or more "keep_conference_alive_if_multiple" participants and at least one of them is a Host. "keep_conference_alive_never": the conference terminates automatically if this is the only remaining participant. Default: "keep_conference_alive_if_multiple" For more information, see Automatically ending a conference.
local_display_name	No	String	The display name of the calling or "from" alias.
presentation_url	No	String	This additional parameter can be specified for RTMP calls to send the presentation stream to a separate RTMP destination.
remote_display_name	No	String	An optional friendly name for this participant. This may be used instead of the participant's alias in participant lists and as a text overlay in some layout configurations.
routing	No	String	Specifies how to route the call: "manual": uses the requested protocol and the defaults for the specified system_location_name. "routing_rule": routes the call according to the configured Call Routing Rules. This means that the dialed alias must match an outgoing Call Routing Rule for the call to be placed (using the protocols, outgoing location and call control systems etc. as configured for that rule). Default: "manual"
streaming	No	Boolean	Identifies the dialed participant as a streaming or recording device. true: the participant is a streaming or recording device false: the participant is not a streaming or recording device Default: false
system_location_name	No	String	The location of the Conferencing Node from which to place the call.

Example service configuration data responses

Response containing service configuration data

This is an example response of service configuration data for a "conference" service type:

{
"status": "success",
"action": "continue",
"result": {
  "service_type": "conference",
  "name": "Alice Jones",
  "service_tag": "abcd1234",
  "description": "Alice Jones personal VMR",
  "pin": "1234",
  "allow_guests": true,
  "guest_pin": "5678",
  "view": "one_main_zero_pips",
  "enable_overlay_text": true,
  "automatic_participants": 
  [
    {
      "remote_alias": "sip:alice@example.com",
      "remote_display_name": "Alice",
      "local_alias": "meet.alice@example.com",
      "local_display_name": "Alice's VMR",
      "protocol": "sip",
      "role": "chair",
      "system_location_name": "London"
    },
    {
      "remote_alias": "rtmp://example.com/live/alice_vmr",
      "local_alias": "meet.alice@example.com",
      "local_display_name": "Alice's VMR",
      "protocol": "rtmp",
      "role": "guest",
      "streaming": true
    }
  ]
  },
"xyz_version": "1.2"
}

Response instructing Pexip Infinity to reject the call

This is an example response that tells Pexip Infinity to reject a call. This could be sent in a 200 OK message, or in a 404 response:

{
"status": "success",
"action": "reject"
}

Participant properties requests

This allows some of the participant's call properties, such as their display name or role, to be changed before they join the conference. This allows you, for example, to anonymize a participant's name or modify their role based on other properties of the call or their associated Identity Provider.

For WebRTC participants it is applied after any PIN entry or SSO steps (and hence has access to Identity Provider attributes).
For SIP/H.323 endpoints, it is applied before any PIN entry steps.

Participant policy is applied after any service configuration policy, and before media location policy.

Request URI: <policy_server_uri>/policy/v1/participant/properties

Pexip Infinity includes the following fields in a participant properties request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call. It is present on both inbound and outbound call requests but is meaningful only for inbound calls.
call_direction	The direction of the call that triggered the request. Values can be: "dial_in": calls in to Pexip Infinity "dial_out": calls dialed out from Pexip Infinity "non_dial": when policy is triggered by other requests that are not related to incoming or outgoing call setup, such as when an H.323 LRQ or a SIP SUBSCRIBE or OPTIONS request is received.
call_tag	An optional call tag that is assigned to a participant.
call_uuid	A unique identifier for the participant's call.
display_count	When included in participant configuration it is the number of screens possessed by the endpoint, if known. This could be either the display count signaled by the endpoint, or as defined by the theme's vendordata.json file. When included in service configuration it is the number of screens signaled by a Microsoft Teams Room when joining via One-Touch Join.
has_authenticated_display_name	Boolean indicating if the participant's display name was provided and authenticated by an Identity Provider.
idp_attributes	This contains any custom Identity Provider attributes for that participant. Each attribute is prefixed with idp_attribute_ when it is referenced as a parameter in external policy. For example, a custom attribute of "locale" would be idp_attribute_locale. Custom attributes for use in participant policy are assigned to Identity Providers in the Advanced options settings when configuring the Identity Provider (Users & Devices > Identity Providers > Advanced options).
idp_uuid	The UUID of the Identity Provider who provided and authenticated the participant's display name, and provided any idp_attributes in participant policy.
local_alias	In the context of service and participant configuration requests, this is the incoming alias (typically the alias that the endpoint has dialed). This is the primary item of information that the policy server will use to return appropriate service configuration data.
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip	The IP address of the Conferencing Node making the request.
p_Asserted-Identity †	The authenticated identity of the user sending the SIP message.
participant_type	The participant type: It can be: "standard": used for most types of calls. "api": when a WebRTC client joins there are normally two requests to policy. The first is for the API participant which has the "api" type. Normally, immediately after the "api" request, a "standard" participant request is made. "api_host": this is a variation of the normal "api" type which also starts the conference if the participant is a Host.
participant_uuid	The uuid associated with the participant.
preauthenticated_role	The participant's role, either "guest", "chair" or null (note that in any jinja statements you need to test for: is None). You should consider the sequence of events that could determine the role's value provided here: For WebRTC participants, participant policy is applied after any PIN entry or SSO steps (which may determine the participant's role). For SIP/H.323 endpoints, participant policy is applied before any PIN entry steps. Local policy is applied after any external policy (which may have modified the role).
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323", "teams" or "mssip". (Note that the protocol is always reported as "api" when a Connect app dials in to Pexip Infinity.)
pseudo_version_id	The Pexip Infinity software build number.
receive_from_audio_mix	The audio mix this participant is receiving e.g. "main".
registered	Boolean indicating whether the remote participant is registered or not.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
send_to_audio_mixes	The audio mixes this participant is sending to. This is a list of dictionaries, each of which contains the key mix_name with a string value (e.g. "main") and optionally contains the key prominent with a boolean value. For example: "send_to_audio_mixes": [ { "mix_name": "main", "prominent": false }, { "mix_name": "french", "prominent": true } ] These attributes are called send_to_audio_mixes_mix_name and send_to_audio_mixes_prominent when they are referenced as parameters in external policy. Currently these are always sent as &send_to_audio_mixes_mix_name=main&send_to_audio_mixes_prominent=False
service_name	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag	The service tag associated with the service_name parameter.
supports_direct_media	Boolean indicating if the service supports direct media or not.
teams_tenant_id	Contains the Microsoft Teams tenant ID on an inbound Teams call to Pexip Infinity for Teams Rooms SIP/H.323 calling.
telehealth_request_id ◊	The telehealth call id.
trigger	The trigger for the policy request. Values: "web", "web_avatar_fetch", "invite", "options", "subscribe", "setup", "arq", "lrq", "two_stage_dialing", "teams", or "unspecified".
unique_service_name	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id	The Pexip Infinity software version number.
† Only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header. Note that the ms_subnet and p_asserted_identity fields use only underscores and lower case characters in their names when used in local policy (normally they are referenced as ms-subnet and p_Asserted-Identity). ‡ Only included in outbound call requests and for breakout rooms. †† Only included in outbound call requests. ◊ Only included in Epic telehealth calls.

This example shows a GET request for participant properties when alice@example.com has dialed meet.bob from a SIP endpoint:

GET /example.com/policy/v1/participant/properties?call_direction=dial_in&protocol=sip&bandwidth=0&vendor=Cisco/CE&encryption=On&registered=False&trigger=invite&remote_display_name=Alice&remote_alias=sip:alice@example.com&remote_address=10.44.151.5&remote_port=64410&call_tag=&idp_uuid=&has_authenticated_display_name=False&supports_direct_media=False&teams_tenant_id=&location=London&node_ip=10.144.101.21&version_id=35&pseudo_version_id=77683.0.0&preauthenticated_role=chair&bypass_lock=False&receive_from_audio_mix=main&display_count=&participant_type=standard&participant_uuid=a13e1e71&local_alias=meet.bob&call_uuid=a13e1e71&breakout_uuid=&send_to_audio_mixes_mix_name=main&send_to_audio_mixes_prominent=False&unique_service_name=meet.bob&service_name=meet.bob&service_tag=

Response to a participant properties request

The response to a participant properties request takes the basic format:

{
"status": "success",
"action": "reject|continue",
"result": { <participant_configuration_data> }
}

where:

"action" is an optional value that, when included, instructs Pexip Infinity how to proceed in failure scenarios:
- "reject" instructs Pexip Infinity to reject the call, and you can optionally specify a rejection reason.
- "continue" use the data supplied in the "result" field.
"result" is a JSON object of key value pairs that override the participant properties provided in the original participant information, or provides a rejection reason. The fields that may be included are listed below. All data fields are optional.

Field name	Required	Type	Description
bypass_lock	No	Boolean	Controls whether the participant can directly enter a locked conference. Default: false
call_tag	No	String	An override for the call tag that is assigned to this participant.
display_count	No	Integer	An override for the number of screens possessed by the endpoint.
disable_overlay_text	No	Boolean	Controls whether the participant overlay text (display name) is disabled. Default: false
layout_group	No	String	The name of the layout group you want to assign to this participant when using participant pinning.
preauthenticated_role	No	String	An override for the participant's role. This must be either "chair" or "guest", or null if the originally supplied value was also null. For SIP and H.323 participants the original value will be null as participant policy is applied before any PIN entry (unlike WebRTC). Thus, returning null in the response means the caller is still prompted for a PIN, whereas chair/guest behaves as if the user had entered the PIN for the specified role.
reject_reason	No	String	An optional reason for rejecting the call (where "action" is "reject"). If supplied it is then subsequently shown to any Connect app users.
remote_alias	No	String	An override for the name of the user or the alias of the endpoint. Note that the original caller alias/name is still recorded in the Pexip Infinity call logs when the participant first tries to connect to a conference.
remote_display_name	No	String	An override for the display name of the participant. It may return null if the originally supplied value was also null. Note that the original caller display name is still recorded in the Pexip Infinity call logs when the participant first tries to connect to a conference.
spotlight	No	Integer	Assigns a spotlight value to this participant. The value assigned here determines the participant's spotlight priority. The lower the number the higher priority they have. Note that when a participant is spotlighted via the client API, the spotlight value is set to the current time (e.g 1710759273) thus values such as 1, 2, 99 and so on assigned here will take priority over values assigned via the client API. You can still unspotlight this participant via the client API.
send_to_audio_mixes	No	List	The audio mixes this participant is sending to. This is a list of dictionaries, each of which contains the key mix_name with a string value (e.g. "main") and optionally contains the key prominent with a boolean value. For example: "send_to_audio_mixes": [ { "mix_name": "main", "prominent": false }, { "mix_name": "french", "prominent": true } ]
receive_from_audio_mix	No	String	The audio mix this participant is receiving e.g. "main".

Example participant properties data responses

Response containing participant properties

This is an example response of participant properties:

{
"status": "success",
"action": "continue",
"result": {
  "preauthenticated_role": "guest",
  "remote_alias": "Witness A alias",
  "remote_display_name": "Witness A",
  "bypass_lock": true
  }
}

Response instructing Pexip Infinity to reject the call

This is an example response that tells Pexip Infinity to reject a call.

{
"status": "success",
"action": "reject",
"result" : {"reject_reason": "Insufficient privileges"}
}

Media location requests

Obtains the system location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant. A media location request is often made after a service configuration data request (and after any participant policy).

Request URI: <policy_server_uri>/policy/v1/participant/location

Pexip Infinity includes the following fields in a media location request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call. It is present on both inbound and outbound call requests but is meaningful only for inbound calls.
call_direction	The direction of the call that triggered the request. Values can be: "dial_in": calls in to Pexip Infinity "dial_out": calls dialed out from Pexip Infinity "non_dial": when policy is triggered by other requests that are not related to incoming or outgoing call setup, such as when an H.323 LRQ or a SIP SUBSCRIBE or OPTIONS request is received.
call_tag	An optional call tag that is assigned to a participant.
has_authenticated_display_name	Boolean indicating if the participant's display name was provided and authenticated by an Identity Provider.
idp_uuid	The UUID of the Identity Provider who provided and authenticated the participant's display name, and provided any idp_attributes in participant policy.
local_alias	For media location and participant avatar requests this contains the originally-dialed incoming alias for the associated service.
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip	The IP address of the Conferencing Node making the request.
p_Asserted-Identity †	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323", "teams" or "mssip". (Note that the protocol is always reported as "api" when a Connect app dials in to Pexip Infinity.)
proxy_node_address	The address of the Proxying Edge Node that is handling the call, if applicable.
proxy_node_location	The system location of the Proxying Edge Node that is handling the call, if applicable.
pseudo_version_id	The Pexip Infinity software build number.
registered	Boolean indicating whether the remote participant is registered or not.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
service_name	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag	The service tag associated with the service_name parameter.
supports_direct_media	Boolean indicating if the service supports direct media or not.
teams_tenant_id	Contains the Microsoft Teams tenant ID on an inbound Teams call to Pexip Infinity for Teams Rooms SIP/H.323 calling.
telehealth_request_id ◊	The telehealth call id.
trigger	The trigger for the policy request. Values: "web", "web_avatar_fetch", "invite", "options", "subscribe", "setup", "arq", "lrq", "two_stage_dialing", "teams", or "unspecified".
unique_service_name	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id	The Pexip Infinity software version number.
† Only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header. Note that the ms_subnet and p_asserted_identity fields use only underscores and lower case characters in their names when used in local policy (normally they are referenced as ms-subnet and p_Asserted-Identity). ◊ Only included in Epic telehealth calls.

This example shows a GET request for the media location to use for alice@example.com:

GET /example.com/policy/v1/participant/location?call_direction=dial_in&protocol=sip&bandwidth=0&vendor=Cisco/CE&encryption=On&registered=False&trigger=invite&remote_display_name=Alice&remote_alias=sip:alice@example.com&remote_address=10.44.151.5&remote_port=64410&proxy_node_address=&proxy_node_location=&call_tag=&idp_uuid=&has_authenticated_display_name=False&supports_direct_media=False&teams_tenant_id=&location=London&node_ip=10.144.101.21&version_id=35&pseudo_version_id=77683.0.0&unique_service_name=meet.bob&service_name=meet.bob&service_tag=&local_alias=meet.bob&request_id=644d4edc"

Media location response

The response to a media location request takes the format:

{
"status": "success",
"result": { <location_data> }
}

where "result" is a JSON object of key value pairs that describes the media location to use. The fields that may be included are:

Field name	Required	Type	Description
location	Yes	String	The name* of the principal location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant.
overflow_locations	No	List	A list of one or more system location names* to handle the media if the principal location has reached its capacity. The order of the list defines the order that the locations are used. Note that if the overflow_locations field is set by external policy then these locations cannot subsequently be manipulated by local policy.
* The returned "name" must match the name of a location configured within Pexip Infinity. If any of the location names included in the response do not match a configured location within Pexip Infinity, the entire response is deemed to have failed and Pexip Infinity will fall back to its own default behavior for that request.

Field name

Required

Type

Description

location

Yes

String

The name of the principal location to use for media allocation. A Conferencing Node assigned to that location will handle the media for the participant.

overflow_locations

List

A list of one or more system location names* to handle the media if the principal location has reached its capacity. The order of the list defines the order that the locations are used.

Note that if the overflow_locations field is set by external policy then these locations cannot subsequently be manipulated by local policy.

* The returned "name" must match the name of a location configured within Pexip Infinity. If any of the location names included in the response do not match a configured location within Pexip Infinity, the entire response is deemed to have failed and Pexip Infinity will fall back to its own default behavior for that request.

Example media location data response

This is an example response containing media location data:

{
  "status": "success",
  "result": {
    "location": "Oslo",
    "overflow_locations": ["London", "Paris", "New York"]
    } 
}

This sets the location to use for media to "Oslo", and sets "London", then "Paris" and finally "New York" as the overflow locations to use if "Oslo" is out of capacity.

Participant avatar requests

Obtains the image to display to represent a conference participant or directory contact.

Request URI: <policy_server_uri>/policy/v1/participant/avatar/<alias> where <alias> is the alias of the participant/contact whose avatar is required.

Pexip Infinity includes the following fields in a participant avatar request:

Parameter	Description
bandwidth	The maximum requested bandwidth for the call. It is present on both inbound and outbound call requests but is meaningful only for inbound calls.
call_direction	The direction of the call that triggered the request. Values can be: "dial_in": calls in to Pexip Infinity "dial_out": calls dialed out from Pexip Infinity "non_dial": when policy is triggered by other requests that are not related to incoming or outgoing call setup, such as when an H.323 LRQ or a SIP SUBSCRIBE or OPTIONS request is received.
call_tag	An optional call tag that is assigned to a participant.
has_authenticated_display_name	Boolean indicating if the participant's display name was provided and authenticated by an Identity Provider.
height *	The required height in pixels of the image to be returned.
idp_uuid	The UUID of the Identity Provider who provided and authenticated the participant's display name, and provided any idp_attributes in participant policy.
local_alias	For media location and participant avatar requests this contains the originally-dialed incoming alias for the associated service.
location *	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip *	The IP address of the Conferencing Node making the request.
p_Asserted-Identity †	The authenticated identity of the user sending the SIP message.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323", "teams" or "mssip". (Note that the protocol is always reported as "api" when a Connect app dials in to Pexip Infinity.)
proxy_node_address	The address of the Proxying Edge Node that is handling the call, if applicable.
proxy_node_location	The system location of the Proxying Edge Node that is handling the call, if applicable.
pseudo_version_id *	The Pexip Infinity software build number.
registered *	Boolean indicating whether the remote participant is registered or not.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
role	The role associated with the remote_alias. Values: "chair" (for Host participants), "guest", or "unknown" (a participant who is at the PIN entry screen, or who is at the Waiting for Host screen but their role has not yet been determined).
service_name	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag	The service tag associated with the service_name parameter.
supports_direct_media	Boolean indicating if the service supports direct media or not.
teams_tenant_id	Contains the Microsoft Teams tenant ID on an inbound Teams call to Pexip Infinity for Teams Rooms SIP/H.323 calling.
trigger	The trigger for the policy request. Values: "web", "web_avatar_fetch", "invite", "options", "subscribe", "setup", "arq", "lrq", "two_stage_dialing", "teams", or "unspecified".
unique_service_name	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id *	The Pexip Infinity software version number.
width *	The required width in pixels of the image to be returned.
* These are the only parameters included in a participant avatar request when Pexip Infinity is retrieving directory information (as opposed to service participant-related information where all parameters are included). † Only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header. Note that the ms_subnet and p_asserted_identity fields use only underscores and lower case characters in their names when used in local policy (normally they are referenced as ms-subnet and p_Asserted-Identity).

This example shows a GET request for a participant avatar for the alias "alice" who is in the conference "meet.bob", where the participant device is an unregistered Connect app:

GET /example.com/policy/v1/participant/avatar/alice?protocol=webrtc&node_ip=10.44.99.2&service_name=meet.bob&registered=False&remote_address=10.44.75.250&version_id=35&service_tag=&bandwidth=0&pseudo_version_id=77683.0.0&vendor=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/55.0.2883.87 Safari/537.36&height=100&unique_service_name=meet.bob&local_alias=meet.bob&remote_port=58426&idp_uuid=&has_authenticated_display_name=False&supports_direct_media=False&call_direction=dial_in&remote_alias=alice&remote_display_name=Alice&width=100&trigger=invite&role=chair&location=London

This example shows a GET request for a participant avatar for the alias "alice" that has been triggered in response to a previous directory information request:

GET /example.com/policy/v1/participant/avatar/alice?node_ip=10.47.2.46&registered=True&version_id=35&height=40&width=40&location=London&pseudo_version_id=77683.0.0

Participant avatar response

The response for an avatar request must return a Content-Type of image/jpeg.

All JPEG images must use the RGB or RGBA color space (CMYK is not supported), and be of the requested size (width, height).

If a valid JPEG image is not returned or the image is the wrong size, Pexip Infinity will return a 404 Not Found response to the caller (i.e. the Connect app) which will then use its standard placeholder participant image.

Directory information requests

Obtains directory information — a list of device or VMR aliases and their associated names. This is used to provide phonebook information to Connect apps that are registered to a Pexip Infinity Conferencing Node.

Request URI: <policy_server_uri>/policy/v1/registrations

Pexip Infinity includes the following fields in a directory information request:

Parameter	Description
call_tag	An optional call tag that is assigned to a participant.
limit	The maximum number of results to return (currently this is always set to 10).
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
node_ip	The IP address of the Conferencing Node making the request.
pseudo_version_id	The Pexip Infinity software build number.
q	The string to lookup in the directory.
registration_alias	The alias of the registered client performing the directory lookup.
version_id	The Pexip Infinity software version number.

This example shows a GET request for directory information where the search string is "ali":

GET /example.com/policy/v1/registrations?q=ali&registration_alias=bob@example.com&limit=10&location=london&node_ip=10.44.155.21&pseudo_version_id=77683.0.0&version_id=35

Directory information response

The response to a directory information request takes the format:

{
"status": "success",
"result": [ <directory_data> ],
"ignore_local": True|False
}

where:

"result" is a JSON list containing objects representing individual directory entries. Each JSON object in the list contains the following fields:

Field name	Required	Description
alias	Yes	The alias of the device or VMR. This is the alias Pexip Infinity will use as the <alias> in the URI in a subsequent participant avatar request, and the alias that Connect apps will dial.
description	Yes	A description or name associated with the alias.
username	Yes	The username associated with the device or VMR. This is currently unused by Pexip Infinity.

The policy server should sort the list of aliases into the order in which it wants them to be presented.

"ignore_local" is optional and defaults to False. If set to True it instructs Pexip Infinity to ignore the aliases of any local services or devices i.e. to only use the aliases returned from the policy server as the directory information. When "ignore_local" is False, Pexip Infinity adds the aliases of any local services or devices to the list of aliases returned by the policy server.

Example directory information responses

This is an example of a JSON dictionary of directory information data containing 2 devices:

{
"status": "success",
"result": 
  [
    {
      "username": "alice",
      "alias": "alice@example.com",
      "description": "Alice's VMR"
    },
    {
      "username": "bob",
      "alias": "bob@example.com",
      "description": "Bob's VMR"
    }
  ]
}

This is an example response that instructs Pexip Infinity to not supply any directory information at all — no aliases are returned by the policy server and it also tells Pexip Infinity to ignore any local aliases ("ignore_local" is True):

{
"status": "success",
"result": [],
"ignore_local": True
}

Registration alias requests

Used to determine whether a device alias is allowed to register to a Conferencing Node.

Request URI: <policy_server_uri>/policy/v1/registrations/<alias> where <alias> is the alias of the device that is making the registration request.

Pexip Infinity includes the following fields in a registration request:

Parameter	Description
auth_type	The authentication method. Values can be: "credentials": username and password credentials are required. "sso": single sign-on (username and password credentials are not required).
location	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
node_ip	The IP address of the Conferencing Node making the request.
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323", "teams" or "mssip". (Note that the protocol is always reported as "api" when a Connect app dials in to Pexip Infinity.) For registration requests this is the registration protocol. Values: "webrtc", "sip", or "h323".
pseudo_version_id	The Pexip Infinity software build number.
remote_address	The IP address of the remote participant.
version_id	The Pexip Infinity software version number.

This example shows a GET request for a registration alias of "alice@example.com":

GET /example.com/policy/v1/registrations/alice@example.com?pseudo_version_id=36402.0.0&protocol=webrtc&location=london&version_id=16&remote_address=10.44.151.5&node_ip=10.44.155.21&auth_type="credentials"

Registration alias response

The response to a registration alias request takes the format:

{
"status": "success",
"action": "reject|continue",
"result": { <alias_data> }
}

where:

"action" instructs Pexip Infinity to either reject the registration or proceed with the registration request:
- "reject" instructs Pexip Infinity to reject the registration (note that "result": {} must also be included in the response).
- "continue" (or any other value except "reject") instructs Pexip Infinity to proceed with the registration request.

"result" is a JSON object of key value pairs that can contain the credentials to use to authenticate the registration request, where the requested auth_type is "credentials". The fields are:

Field name	Required	Description
username	No	The username associated with the device.
password	No	The password associated with the device and username. Note that the password is sent "in the clear" so we recommend using a secure https connection to your policy server.

Field name

Required

Description

username

The username associated with the device.

password

The password associated with the device and username.

Note that the password is sent "in the clear" so we recommend using a secure https connection to your policy server.

The device alias may register if it supplies matching credentials.

Use "result": {} if:

the requested auth_type is "sso", or
it is a rejection response, or
to fall back to Pexip Infinity's default behavior (to check if the alias and optionally any associated credentials are configured in its local database of allowed aliases).

If "status" is not "success" or an error code e.g. 404 is returned, then Pexip Infinity will fall back to its own default behavior.

Example registration alias responses

Allowed alias (with authentication): this is an example response containing the required credentials for an allowed alias (the device must then supply the matching credentials to be permitted to register):

{
"status": "success",
"result": {
  "username": "alice",
  "password": "password123"
  }
}

Allowed alias (without authentication): this is an example response that allows the alias to register without authentication (not recommended):

{
"status": "success",
"result": {
	 "username": "",
	 "password": ""
	 }
}

The response must include username/password with empty fields.

Denied alias: this is an example response to reject the requested alias:

{
"status": "success",
"action": "reject",
"result": {}
}

Fallback to local database: this is an example response to fall back to Pexip Infinity's default behavior,:

{
"status": "success",
"action": "continue",
"result": {}
}

Summary of request parameters per request type

This table summarizes which fields are included by Pexip Infinity in each request type:

Parameter	Description	Service config	Participant config	Media location	Participant avatar	Directory info	Registration alias
auth_type	The authentication method. Values can be: "credentials": username and password credentials are required. "sso": single sign-on (username and password credentials are not required).
bandwidth	The maximum requested bandwidth for the call. It is present on both inbound and outbound call requests but is meaningful only for inbound calls.
breakout_uuid	The uuid of a breakout room (if applicable).
call_direction	The direction of the call that triggered the request. Values can be: "dial_in": calls in to Pexip Infinity "dial_out": calls dialed out from Pexip Infinity "non_dial": when policy is triggered by other requests that are not related to incoming or outgoing call setup, such as when an H.323 LRQ or a SIP SUBSCRIBE or OPTIONS request is received.
call_tag	An optional call tag that is assigned to a participant.
call_uuid	A unique identifier for the participant's call.
display_count	When included in participant configuration it is the number of screens possessed by the endpoint, if known. This could be either the display count signaled by the endpoint, or as defined by the theme's vendordata.json file. When included in service configuration it is the number of screens signaled by a Microsoft Teams Room when joining via One-Touch Join.
has_authenticated_display_name	Boolean indicating if the participant's display name was provided and authenticated by an Identity Provider.
height *	The required height in pixels of the image to be returned.
idp_attributes	This contains any custom Identity Provider attributes for that participant. Each attribute is prefixed with idp_attribute_ when it is referenced as a parameter in external policy. For example, a custom attribute of "locale" would be idp_attribute_locale. Custom attributes for use in participant policy are assigned to Identity Providers in the Advanced options settings when configuring the Identity Provider (Users & Devices > Identity Providers > Advanced options).
idp_uuid	The UUID of the Identity Provider who provided and authenticated the participant's display name, and provided any idp_attributes in participant policy.
limit	The maximum number of results to return (currently this is always set to 10).
local_alias	In the context of service and participant configuration requests, this is the incoming alias (typically the alias that the endpoint has dialed). This is the primary item of information that the policy server will use to return appropriate service configuration data. For media location and participant avatar requests this contains the originally-dialed incoming alias for the associated service.
location *	The name of the Pexip Infinity system location associated with the Conferencing Node making the request/notification.
ms-subnet †	The sender's subnet address.
node_ip *	The IP address of the Conferencing Node making the request.
p_Asserted-Identity †	The authenticated identity of the user sending the SIP message.
participant_type	The participant type: It can be: "standard": used for most types of calls. "api": when a WebRTC client joins there are normally two requests to policy. The first is for the API participant which has the "api" type. Normally, immediately after the "api" request, a "standard" participant request is made. "api_host": this is a variation of the normal "api" type which also starts the conference if the participant is a Host.
participant_uuid	The uuid associated with the participant.
preauthenticated_role	The participant's role, either "guest", "chair" or null (note that in any jinja statements you need to test for: is None). You should consider the sequence of events that could determine the role's value provided here: For WebRTC participants, participant policy is applied after any PIN entry or SSO steps (which may determine the participant's role). For SIP/H.323 endpoints, participant policy is applied before any PIN entry steps. Local policy is applied after any external policy (which may have modified the role).
protocol	The call protocol. Values: "api", "webrtc", "sip", "rtmp", "h323", "teams" or "mssip". (Note that the protocol is always reported as "api" when a Connect app dials in to Pexip Infinity.) For registration requests this is the registration protocol. Values: "webrtc", "sip", or "h323".
proxy_node_address	The address of the Proxying Edge Node that is handling the call, if applicable.
proxy_node_location	The system location of the Proxying Edge Node that is handling the call, if applicable.
pseudo_version_id *	The Pexip Infinity software build number.
q	The string to lookup in the directory.
receive_from_audio_mix	The audio mix this participant is receiving e.g. "main".
registered *	Boolean indicating whether the remote participant is registered or not.
registration_alias	The alias of the registered client performing the directory lookup.
remote_address	The IP address of the remote participant.
remote_alias	The name of the user or the registered alias of the endpoint. The remote_alias may include scheme information, for example sip:alice@example.com.
remote_display_name	The display name of the remote participant.
remote_port	The IP port of the remote participant.
role	The role associated with the remote_alias. Values: "chair" (for Host participants), "guest", or "unknown" (a participant who is at the PIN entry screen, or who is at the Waiting for Host screen but their role has not yet been determined).
send_to_audio_mixes	The audio mixes this participant is sending to. This is a list of dictionaries, each of which contains the key mix_name with a string value (e.g. "main") and optionally contains the key prominent with a boolean value. For example: "send_to_audio_mixes": [ { "mix_name": "main", "prominent": false }, { "mix_name": "french", "prominent": true } ] These attributes are called send_to_audio_mixes_mix_name and send_to_audio_mixes_prominent when they are referenced as parameters in external policy. Currently these are always sent as &send_to_audio_mixes_mix_name=main&send_to_audio_mixes_prominent=False
service_name ‡	The service name. This will match the name field returned by the policy server from the original service configuration request.
service_tag ††	The service tag associated with the service_name parameter.
supports_direct_media	Boolean indicating if the service supports direct media or not.
teams_tenant_id	Contains the Microsoft Teams tenant ID on an inbound Teams call to Pexip Infinity for Teams Rooms SIP/H.323 calling.
telehealth_request_id ◊	The telehealth call id.
third_party_passcode	The passcode field provided by the Microsoft Teams Room calendaring service*, extracted from the meeting invitation.
trigger	The trigger for the policy request. Values: "web", "web_avatar_fetch", "invite", "options", "subscribe", "setup", "arq", "lrq", "two_stage_dialing", "teams", or "unspecified".
unique_service_name ‡	The unique name used by Pexip Infinity to identify the service: For "gateway" services this is the matching rule name followed by a unique identifier (so as to distinguish between separate calls that match the same rule). For all other services, this is the same as the service_name parameter.
vendor	System details about the remote participant, such as manufacturer name and version number for hard endpoints, or browser and operating system details for soft clients.
version_id *	The Pexip Infinity software version number.
width *	The required width in pixels of the image to be returned.
* These are the only parameters included in a participant avatar request when Pexip Infinity is retrieving directory information (as opposed to service participant-related information where all parameters are included). † Only included if the request was triggered by a SIP message, and the parameter is included as a field in the SIP message header. Note that the ms_subnet and p_asserted_identity fields use only underscores and lower case characters in their names when used in local policy (normally they are referenced as ms-subnet and p_Asserted-Identity). ‡ Only included in outbound call requests and for breakout rooms. †† Only included in outbound call requests. ◊ Only included in Epic telehealth calls.