Sipfront API¶

Sipfront provides a REST API to programmatically control various aspects of the platform.

Data Format¶

To send data to the API, use form-encoded request bodies. The API responds with JSON data and standard HTTP response codes.

Authentication¶

Authentication on the API is performed using Basic Authentication over HTTPS.

Test steps¶

When performing tests on the API, you have to understand how these tests are structured (in fact it's the same on the Web UI, but there it's graphically abstracted).

Tests go through one or more steps, each containing one or more actions. The notion for these steps and actions is by addressing them with the prefix step.$step_index.$action_index, for instance step.0.0 to address attributes for the first action in the first step.

The figure below outlines an example test for a basic call with two steps. The first step is to prepare the called party by registering the users in the first action of this step, then wait for inbound calls as second action of this step. The second step is to start initiating calls from the calling party to these called parties that we have prepared in the previous step.

In order to set the expire value of the called parties to one hour when registering them in the first action of the first step, you would provide the attribute step.0.0.regexpire=3600. To initiate exactly 10 new calls from the calling parties to the called parties in the first action of the second step, you would set step.1.0.max_total_calls=10.

API Endpoints¶

Explore endpoints¶

#!/bin/sh
AUTH="$public_key:$secret"
curl -X GET \
    -u "$AUTH" \
    https://app.sipfront.com/api/v2/ | jq .
echo

Explore available tests and their parameters¶

#!/bin/sh
AUTH="$public_key:$secret"
curl -X GET \
    -u "$AUTH" \
    https://app.sipfront.com/api/v2/tests | jq .
echo

Run specific test¶

You can run a specific test by passing the test name as parameter.

#!/bin/sh
AUTH="$public_key:$secret"
curl https://app.sipfront.com/api/v2/tests/run \
    -X POST \
    -u "$AUTH" \
    -F test.name=$your_test_name

Instead of passing the options as form-data, you can also use json to set the parameters:

#!/bin/sh
AUTH="$public_key:$secret"
curl https://app.sipfront.com/api/v2/tests/run \
    -X POST \
    -u "$AUTH" \
    -H "Content-Type: application/json" \
    --data '{"test.name": "$your_test_name"}'

Either way, you will receive a json response as follows in your response:

{
  "data": {
    "report_url": "https://app.sipfront.com/run/details/bae59eae-c123-45ee-6789-6cb5e9a2b1c2",
    "session_id": "bae59eae-c723-11ee-8347-6cb5e9a2b1c2",
    "status_url": "https://app.sipfront.com/api/v2/runs/bae59eae-c123-45ee-6789-6cb5e9a2b1c2/status"
  },
  "status": 200
}

Override the dialled destination when running a test¶

When you create a test on the web interface, you have to specify the number to dial. However, if you trigger the same test via the API over and over again, with the only difference being the dialed destination, you don't have to create a new test per destination. Instead, you can override this parameter as follows:

#!/bin/sh
AUTH="$public_key:$secret"
curl https://app.sipfront.com/api/v2/tests/run \
    -X POST \
    -u "$AUTH" \
    -F test.name=$your_test_name \
    -F step.1.0.dial_destination="431231234"

Using json, you would pass "step.1.0.dial_destination": "431231234" as a parameter accordingly.

Run a test in kiosk mode¶

By default, the API will return a report URL to inspect the results which requires you to be logged in to the Sipfront web interface. If you'd rather embed the results page or would like to publicly share it, you can launch the test in kiosk mode by passing report.mode=kiosk (or "report.mode": "kiosk" in json) and will receive the publicly shareable link.

#!/bin/sh
AUTH="$public_key:$secret"
curl https://app.sipfront.com/api/v2/tests/run \
    -X POST \
    -u "$AUTH" \
    -F test.name=$your_test_name \
    -F report.mode="kiosk"

which results the same result data, but the data.report_url will point to the publicly sharable link.

{
  "data": {
    "report_url": "https://app.sipfront.com/kiosk/26e3edac-1234-5678-b5cf-18fe1d04aabb/bae59eae-c123-45ee-6789-6cb5e9a2b1c2",
    "session_id": "bae59eae-c723-11ee-8347-6cb5e9a2b1c2",
    "status_url": "https://app.sipfront.com/api/v2/runs/bae59eae-c123-45ee-6789-6cb5e9a2b1c2/status"
  },
  "status": 200
}

Query the status of a test¶

The result data contains a data.status_url which you can use to query the status of a test run.

#!/bin/sh
AUTH="$public_key:$secret"
curl https://app.sipfront.com/api/v2/runs/bae59eae-c123-45ee-6789-6cb5e9a2b1c2/status \
    -u "$AUTH"

While a test is running, you will receive run.status set to running:

{
  "run": {
    "status": "running"
  },
  "status": 200
}

A finished test yields the detailed information about the test run, again with run.status indicating whether the test run succeeded or not, and if it failed, run.result_description giving you the reason:

{
  "run": {
    "agentpool_name": "eu-central-1",
    "has_passed": 1,
    "id": 12345,
    "is_failed": 0,
    "is_finished": 1,
    "project_id": 1,
    "project_name": "my-project-name",
    "result_description": "",
    "session_id": "bae59eae-c123-45ee-6789-6cb5e9a2b1c2",
    "started_at": "2024-02-09 08:20:18",
    "status": "passed",
    "stopped_at": "2024-02-09 08:22:13",
    "tags": "[\"media\", \"prod\", \"validation\"]",
    "test_id": 123,
    "test_name": "your-test-name",
    "testcase_name": "Media analysis for Audio Call"
  },
  "status": 200
}