PIN — VoIP (ServiceID = 2)›PIN CallerID Functions

Add CallerID to PIN

Bind a CallerID to a PIN.

GETPOSThttps://www.parlacom.net/cgi-bin/parla?function=addpincallerid

Auth required

Authentication & headers

Every Mercurius call is authenticated. Prefer sessionid from login; otherwise send admin + adminpwd on every request. Credentials go in the query string (GET) or the form body (POST) — Mercurius does not use Authorization headers.

Header	When	Value
Host	Always	www.parlacom.net
Accept	Recommended	application/xml, text/html;q=0.5
Content-Type	Required for POST	application/x-www-form-urlencoded
User-Agent	Recommended	your-app/1.0 (+contact)
Accept-Encoding	Optional	gzip, deflate

curl

curl -X POST 'https://www.parlacom.net/cgi-bin/parla' \
  -H 'Accept: application/xml' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'User-Agent: my-app/1.0' \
  --data-urlencode 'function=addpincallerid' \
  --data-urlencode 'company=parla' \
  --data-urlencode 'output_type=json' \
  --data-urlencode 'sessionid=6173101117159668311613718971931311572197'

fetch (browser / Node)

await fetch('https://www.parlacom.net/cgi-bin/parla', {
  method: 'POST',
  headers: {
    'Accept': 'application/xml',
    'Content-Type': 'application/x-www-form-urlencoded',
    'User-Agent': 'my-app/1.0',
  },
  body: new URLSearchParams({
    function: 'addpincallerid',
    company: 'parla',
    output_type: 'json',
    sessionid: '6173101117159668311613718971931311572197',
  }),
});

Fallback (no session): admin=parla_admin&adminpwd=••••• in place of sessionid.

Parameters

Name	Required	Description	Example
function	required	Endpoint function name (fixed for this call).	`addpincallerid`
company	required	Your company identifier.	`parla`
output_type	required	`json` (XML/JSON payload) or `html` (rendered).	`json`
login	optional	Login owning the resource. Defaults to `admin`.	`clovis1234`
sessionid	optional	Session token from `login`. Omit if using admin/adminpwd.	`6173101117159668311613718971931311572197`
admin	optional	Admin login (required if no sessionid).	`parla_admin`
adminpwd	optional	Admin password (required if no sessionid).	`••••••••`
pin	required	Target PIN.	`1000001`
callerid	required	CallerID to bind.	`5511999998888`

Example request — GET

https://www.parlacom.net/cgi-bin/parla?function=addpincallerid&company=parla&output_type=json&login=clovis1234&sessionid=6173101117159668311613718971931311572197&admin=parla_admin&adminpwd=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2&pin=1000001&callerid=5511999998888

Example request — POST

POST https://www.parlacom.net/cgi-bin/parla
 HTTP/1.1
Host: www.parlacom.net
Content-Type: application/x-www-form-urlencoded
 
function=addpincallerid&company=parla&output_type=json&login=clovis1234&sessionid=6173101117159668311613718971931311572197&admin=parla_admin&adminpwd=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2&pin=1000001&callerid=5511999998888

Example response

<!-- Success -->
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <errorcode>0</errorcode>
  <pin>1000001</pin>
  <callerid>5511999998888</callerid>
  <message>CallerID bound</message>
</response>

<!-- Failure -->
<?xml version="1.0" encoding="UTF-8"?>
<response>
  <errorcode>101</errorcode>
  <message>Invalid session or missing parameter</message>
</response>

Notes

All responses include an <errorcode> tag; 0 means success.
Pass output_type=html to receive the rendered ParlaBox view instead of XML.
See the full error code list.

Errors

Error responses

Mercurius returns HTTP 200 for both success and business errors — the outcome lives in the <errorcode> envelope. Treat any non-zero errorcode as a failure and read <errortext> for a human-readable reason. HTTP 4xx/5xx only occur when the gateway itself rejects the request.

errorcode	HTTP	Name	Meaning	When
0	200	OK	Request succeeded. The payload sits alongside <errorcode>0</errorcode>.	Every successful call.
1	200	MissingParameter	A required parameter is missing or empty.	You omitted a field marked required in the Parameters table.
2	200	InvalidParameter	A parameter value failed validation (format, range, type).	e.g. malformed date, non-numeric id, unknown enum value.
3	200	AuthFailed	sessionid is missing, expired, or admin/adminpwd is wrong.	Session timed out (30 min idle) or credentials are invalid.
4	200	Forbidden	The caller is authenticated but not allowed to perform this action.	Non-admin calling an admin function, or accessing another tenant.
5	200	NotFound	The referenced resource does not exist.	Unknown pin, userlogin, invoiceid, deviceid, etc.
6	200	Conflict	The resource already exists or the state transition is invalid.	Duplicate userlogin, re-activating an active service, etc.
9	200	RateLimited	Too many requests from this session/IP.	Sustained bursts (>10 req/s) or repeated auth failures.
99	200	InternalError	Unexpected server-side error.	Transient — retry with exponential backoff.
-1	400	BadRequest	The gateway rejected the HTTP request before reaching the app.	Malformed URL, unknown function name, body too large.
-1	504	GatewayTimeout	Upstream took longer than 15s to respond.	Backend congestion — retry after a short delay.

Recovery

errorcode → action mapping

Use this table to decide, per errorcode, whether the client must call login again, retry the original request, or surface the failure to the user. The shared session manager follows these same rules.

errorcode	Name	Action	Retry original?	Backoff	Guidance
0	OK	No action	No	—	Success — process the payload alongside errorcode=0.
1	MissingParameter	Fix input	No	—	Add the missing required parameter and re-send. Retrying the exact same request will fail again.
2	InvalidParameter	Fix input	No	—	Correct the malformed value (format/range/enum) and re-send.
3	AuthFailed	Call login → retry	Yes — after login	—	sessionid is missing, expired (30 min idle), or admin/adminpwd is wrong. Call login, replace sessionid, then retry the original request. The shared session manager does this automatically.
4	Forbidden	Re-authorize (no retry)	No	—	Authenticated but not entitled to this function/tenant. Do NOT call login again with the same credentials — it will succeed but the retry will still return 4. Escalate or use an authorized account.
5	NotFound	Fix input	No	—	The resource id doesn't exist. Verify the identifier before re-sending.
6	Conflict	Fix input	No	—	Duplicate or invalid state transition. Reconcile state (e.g. read current record) before retrying.
9	RateLimited	Back off, then retry	Yes — after delay	≥30s, exponential	Too many requests. Wait for the retry-after hint (or ≥30s) and re-send the same request. Do NOT call login — it counts against the same limit.
99	InternalError	Retry same request	Yes — same request	1s, 2s, 4s (max 3 tries)	Transient server-side failure. Retry the identical request with exponential backoff.
-1	BadRequest (HTTP 400)	Abort	No	—	Gateway rejected the request shape (unknown function, body too large). Fix the client — retrying is pointless.
-1	GatewayTimeout (HTTP 504)	Retry same request	Yes — after delay	2s, 5s, 10s	Upstream slow. Retry the same request after a short delay; do NOT re-login.

Rule of thumb: only errorcode=3 should trigger a fresh login. Codes 1/2/5/6 are caller bugs — fix the input. Code 4 means the account isn't entitled, so re-logging in with the same credentials won't help. Transient codes (9, 99, HTTP 504) retry the same request with backoff.

0 · OK

<?xml version="1.0" encoding="UTF-8"?>
<parla>
  <errorcode>0</errorcode>
  <errortext>OK</errortext>
  <!-- endpoint-specific payload here -->
</parla>

1 · MissingParameter

<?xml version="1.0" encoding="UTF-8"?>
<parla>
  <errorcode>1</errorcode>
  <errortext>Missing parameter: userlogin</errortext>
</parla>

2 · InvalidParameter

<?xml version="1.0" encoding="UTF-8"?>
<parla>
  <errorcode>2</errorcode>
  <errortext>Invalid parameter: startdate must be YYYY-MM-DD</errortext>
</parla>

3 · AuthFailed

<?xml version="1.0" encoding="UTF-8"?>
<parla>
  <errorcode>3</errorcode>
  <errortext>Authentication failed</errortext>
</parla>

4 · Forbidden

<?xml version="1.0" encoding="UTF-8"?>
<parla>
  <errorcode>4</errorcode>
  <errortext>Access denied for function</errortext>
</parla>

5 · NotFound

<?xml version="1.0" encoding="UTF-8"?>
<parla>
  <errorcode>5</errorcode>
  <errortext>Record not found</errortext>
</parla>

Try it out

Fields are pre-filled from the documented examples so the query string (GET) and form body (POST) build themselves. Tweak any value, switch methods, and send.

function = addpincallerid(fixed)

companyrequiredYour company identifier.output_typerequired`json` (XML/JSON payload) or `html` (rendered).loginoptionalLogin owning the resource. Defaults to `admin`.sessionidoptionalSession token from `login`. Omit if using admin/adminpwd.adminoptionalAdmin login (required if no sessionid).adminpwdoptionalAdmin password (required if no sessionid).pinrequiredTarget PIN.calleridrequiredCallerID to bind.

curl

curl -X POST 'https://www.parlacom.net/cgi-bin/parla' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'function=addpincallerid&function=addpincallerid&company=parla&output_type=json&login=clovis1234&sessionid=6173101117159668311613718971931311572197&admin=parla_admin&adminpwd=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2&pin=1000001&callerid=5511999998888'

fetch (JS)

const res = await fetch("https://www.parlacom.net/cgi-bin/parla", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: "function=addpincallerid&function=addpincallerid&company=parla&output_type=json&login=clovis1234&sessionid=6173101117159668311613718971931311572197&admin=parla_admin&adminpwd=%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2%E2%80%A2&pin=1000001&callerid=5511999998888",
});
const xml = await res.text();