API call with SIP privacy headers
Author Image

By: Aivis Olsteins

In News


API voice call with SIP Identity and Privacy headers

Most carriers now required properly set SIP Identity and Privacy headers. Here is how to set them in the API call.

When sending voice calls over SIP trunks, it is frequently needed to set specific SIP headers in order to comply with requirements of upstream carriers or pass additional information within call. It can be done when sending SIP calls via API.

One of the most popular case is setting SIP Privacy headers to comply with many European carriers requirements. The purpose of SIP Privacy headers are:

  1. to identify the origin of the call “out of band”. i. e. outside of parameters available to end users, and
  2. pass requested privacy setting to the upstream carrier, while preserving the information about caller for identification and subsequent rating and routing purposes.


The above two points are usually interconnected: most carriers now require both settings to be set in SIP message. The first header, asserting the identity of the caller is P-Asserted-Identity and has format as in this example:


P-Asserted-Identity tel:+3312345678


Note, that phone number is prefixed by tel: string and comes in full E.164 format including plus symbol. This field is usually used to determine the origin country/area of the call and therefore used to make decision how the call should be rated and routed. In countries and carriers which since last year make distinction between calls originated within or outside of EU/EEA, this is the determining field. Absence of this field might cause call to be rated most highest rate (sometimes unreasonably high – so beware) or rejected outright.


The other usually required attribute tells carrier whether callers wishes to display it's identity to called party or not. The SIP header name is “Privacy” and example usage is:


Privacy: Id


The example above shows that downstream carrier should use From SIP header to present as the caller ID to the called party.


Now, let's compose the API call with above headers:


POST /voice/call/play 

"to": "123456",
"from": "112233",
"play": "http://server.domain.com/voices/hello.wav"
"play": "http://server.domain.com/voices/main-message.wav"
"play": "http://server.domain.com/voices/goodbye-thanks.wav"
"carrier_id" : "74445609",
"osip_P-Asserted-Identity" : "tel:+3312345678",
"osip_Privacy" : "Id"

So the above example tells upstream carrier that the real caller identity is +3312345678, but the caller should see on their display 112233 as the caller ID. The call is now compliant with carriers requirement and will be properly rated and routed as originated from within EU/EEA country (+33 France prefix).

Note, that custom SIP headers are prefixed by osip_ string and then follow exactly as typed.

Leave a comment
About Author
Author Image
My name is Aivis Olsteins and I am owner of DataTechLabs. My experience in Telecoms started in early 1990's and I have worked in multiple technical positions in mobile, messaging and data networks. My expertise lies in telecom networks, database systems, distributed processing and large data analysis. These posts are my attempt to share my knowledge with everyone who might find it useful.

Get in Touch

If you have something to say, please use the contact form below to get in touch with us. We will get back to you as soon as possible.

Mail Us

DataTechLabs SIA, Muzikas str 12A
Jurmala, LV-2008, Latvia.

Call Us

+371 67 66 09 01
+ 1 202 499 1550

E-mail Us