v20 API errors

mwiener1 · Oct 7, 2024

When trying to send a PATCH, as described in the docs for /Backups/Pbx.SetBackupSettings, we get returned a 400 about a missing "delta" field.

Can someone point me in the direction on what other data I need to send it?

{"error":{"code":"","message":"The input was not valid.\n\ndelta:\nThe delta field is required.","details":[{"code":"","message":"The input was not valid."},{"code":"","target":"delta","message":"The delta field is required."}]}

stubh · Jun 23, 2025

Did you ever end up solving this issue? If so, what did you do?

spflug · Jun 24, 2025

Maybe this snip points you in the right direction.

Code:

$uri = "https://$tcxurl/xapi/v1/SystemStatus"
    $response =(Invoke-RestMethod -Uri $uri -Headers $headers -Method GET  -ContentType "application/json")
    $fqdn = $response.FQDN


    #Write-Host $m1 $m2
    $hour = [int]$fqdn.substring(1,1) +1
    $minute = $fqdn.substring(3,1)
    $second = 0

    # Erstelle ein DateTime-Objekt mit den einzelnen Werten
    $time = [datetime]::new(1, 1, 1, $hour, $minute, 0)

    # Gib die Zeit im gewünschten Format aus
    $timeString = $time.ToString("HH:mm:ss")
 

    $jsonObject = [PSCustomObject]@{
        settings = [PSCustomObject]@{
            ScheduleEnabled = $true
            Rotation = 1
            Schedule = [PSCustomObject]@{
                Time = "$timeString"
                RepeatHours = 1
                ScheduleType = "Daily"
                Day = "Sunday"
            }
            Contents = [PSCustomObject]@{
                Recordings = $false
                EncryptBackup = $false
                FQDN = $true
                CallHistory = $true
                License = $true
                PhoneProvisioning = $true
                Prompts = $true
                VoiceMails = $true
                DisableBackupCompression = $true
            }
        }
    }

    $jsonuserpatch = $jsonObject | ConvertTo-Json  -Depth 5

    $uri = "https://$tcxurl/xapi/v1/Backups/Pbx.SetBackupSettings"
    $response = Invoke-WebRequest -Uri $uri -Headers $headers -Body $jsonuserpatch -Method POST -ContentType "application/json"

stubh · Jun 24, 2025

I am able to make the get system status request without issue. I am having some issues with creating user accounts asking for the delta field, and this issue was similar in nature, so I was wondering what or if they did to fix the issue

paulodagraca · Jun 24, 2025

Hello,

With this post I would like to help you with the API in Python.
This Python script will connect to the 3CX server and create an extension.

So save this to your server with name "mytest.py"
Before you start, please enter your server login details for it to work.
Start with: python3 mytest.py

Python:

import requests
import json

# Fill these 3 lines with real information
serverFQDN = "{FQDN}:{port}"
userName = "{owner}"
passWord = "{password}"


# Authenticate on 3CX server with Username and Password to get an Access Token
# POST /webclient/api/Login/GetAccessToken
url = "https://" + serverFQDN + "/webclient/api/Login/GetAccessToken"
headers = {"Content-Type": "application/json; charset=utf-8"}
data = {"SecurityCode":"", "Username":userName, "Password":passWord}
response = requests.post(url, headers=headers, json=data)
access_token = response.json() ['Token']['access_token']
#print ("access_token ", access_token)
# Nah, it's all good


# Get first connection with 3CX server, request version
# GET /xapi/v1/Defs?%24select=Id
url = "https://" + serverFQDN + "/xapi/v1/Defs?%24select=Id"
headers = {"Content-Type": "application/json; charset=utf-8", 'Authorization': 'Bearer ' + access_token}
data = {}
response = requests.get(url, headers=headers, json=data)
#print (response.json())
# Who cares realy?


# Create new Extension on the 3CX Server
# POST /xapi/v1/Users
url = "https://" + serverFQDN + "/xapi/v1/Users"
headers = {"Content-Type": "application/json; charset=utf-8", 'Authorization': 'Bearer ' + access_token}
data = {
    "AccessPassword": "QrzxYQwa5!",
    "EmailAddress": "[email protected]",
    "FirstName": "TestFirstName",
    "Id": 0,
    "Language": "EN",
    "LastName": "TestLastName",
    "Number": "211",
    "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",
    "SendEmailMissedCalls": True,
    "VMEmailOptions": "Notification",
    "Require2FA": True
}
# Here we go...
response = requests.post(url, headers=headers, json=data)
print (response.json())
# Okay, it's done!

For me this works fine, tested on 2 servers.

Paulo

stubh · Jun 24, 2025

paulodagraca said:

Hello,

With this post I would like to help you with the API in Python.
This Python script will connect to the 3CX server and create an extension.

So save this to your server with name "mytest.py"
Before you start, please enter your server login details for it to work.
Start with: python3 mytest.py

Python:

import requests
import json

# Fill these 3 lines with real information
serverFQDN = "{FQDN}:{port}"
userName = "{owner}"
passWord = "{password}"


# Authenticate on 3CX server with Username and Password to get an Access Token
# POST /webclient/api/Login/GetAccessToken
url = "https://" + serverFQDN + "/webclient/api/Login/GetAccessToken"
headers = {"Content-Type": "application/json; charset=utf-8"}
data = {"SecurityCode":"", "Username":userName, "Password":passWord}
response = requests.post(url, headers=headers, json=data)
access_token = response.json() ['Token']['access_token']
#print ("access_token ", access_token)
# Nah, it's all good


# Get first connection with 3CX server, request version
# GET /xapi/v1/Defs?%24select=Id
url = "https://" + serverFQDN + "/xapi/v1/Defs?%24select=Id"
headers = {"Content-Type": "application/json; charset=utf-8", 'Authorization': 'Bearer ' + access_token}
data = {}
response = requests.get(url, headers=headers, json=data)
#print (response.json())
# Who cares realy?


# Create new Extension on the 3CX Server
# POST /xapi/v1/Users
url = "https://" + serverFQDN + "/xapi/v1/Users"
headers = {"Content-Type": "application/json; charset=utf-8", 'Authorization': 'Bearer ' + access_token}
data = {
    "AccessPassword": "QrzxYQwa5!",
    "EmailAddress": "[email protected]",
    "FirstName": "TestFirstName",
    "Id": 0,
    "Language": "EN",
    "LastName": "TestLastName",
    "Number": "211",
    "PromptSet": "1e6ed594-af95-4bb4-af56-b957ac87d6d7",
    "SendEmailMissedCalls": True,
    "VMEmailOptions": "Notification",
    "Require2FA": True
}
# Here we go...
response = requests.post(url, headers=headers, json=data)
print (response.json())
# Okay, it's done!

For me this works fine, tested on 2 servers.

Paulo

You are a wizard. I did have to tweak getting the token since I am grabbing that from xapi/v1/connect/token. But that posts with a python script. Now I need to figure out what my original script was not doing and what your is so I can fix that and my automation. You are the best! Thank you for coming back for me!

paulodagraca · Jun 24, 2025

Hello mwiener1,

Where did you find the information about the PATCH option for /Backups/Pbx.SetBackupSettings ?
I don't seem to find it, only covers the GET and POST message, as far as I can find it.

For the POST data it should be:

JSON:

{
  "settings": {
    "Contents": {
      "CallHistory": True,
      "EncryptBackup": False,
      "EncryptBackupPassword": "",
      "FQDN": True,
      "License": True,
      "PhoneProvisioning": True,
      "Prompts": True,
      "Recordings": True,
      "VoiceMails": True
    },
    "Rotation": 5,
    "Schedule": {
      "Day": "Sunday",
      "RepeatHours": 0,
      "ScheduleType": "Daily",
      "Time": "21:00:00.0000000"
    },
    "ScheduleEnabled": True
  }
}

But i think spflug did already cover this one with his code.
Are you okay with the API now, or still running in some issues?

Paulo

stubh · Jun 25, 2025

I am totally good. I got it working this morning. I think it had something to do with the way I was shipping the json data for the new users. Completely working. Fully armed and operational.

DAndersonn@bis. itk · Jul 2, 2025

stubh said:
I am totally good. I got it working this morning. I think it had something to do with the way I was shipping the json data for the new users. Completely working. Fully armed and operational.

Can you tell me, what you did to get this working?
I´m struggling with the

"message": "The delta field is required.",
"target": "delta"

paulodagraca · Jul 2, 2025

Hello DAndersonn@bis. itk,

What software, script are you using?
Did you start from some default demo, where did you find this.
What programming language do you use?

Please scroll up, and look at the Python code example, that works fine.
Not just that it works, you can look at how this has been done.

Paulo

stubh · Jul 2, 2025

DAndersonn@bis. itk said:
Can you tell me, what you did to get this working?
I´m struggling with the

"message": "The delta field is required.",
"target": "delta"

It seems like the delta error comes in when the json you are shipping in with the query is does not fit the schema format it is looking for. It could be its formatted incorrectly or there is a field not spelled right, or its not getting passed as a json string. Try making a patch request to a test users account using /Users(user_id) and in the body send json to update just one field, like FirstName and then work up to bigger queries from there.
I also pulled a very helpful yaml from github with great documentation on endpoints, input schema etc.

https://github.com/3cx/xapi-tutorial/blob/master/swagger.yaml

DAndersonn@bis. itk · Jul 3, 2025

Thanks for your help.
Could figure it out. I´m pretty new to JSON and API requests, so it took a little longer.

The JSON "Post" has to look like this:

JSON:

{
    "FirstName": "Daniel",
    "LastName": "ApiTest",
    "EmailAddress": "[email protected]",
    "Number": "252",
    "Id": 0,
    "Groups": [
        {
            "GroupId": 326,
            "Number": "252",
            "MemberName": "ApiTest, Daniel",
            "Name": "TestAPI",
            "Type": "Extension",
            "CanDelete": true,
            "Id": 0,
            "Rights": {
                "RoleName": "users"
            }
        }
    ]
}

I needed to insert the "Groups" array.

stubh · Jul 3, 2025

Yeah, there are a few "hidden" items inside objects. Like user Groups and rights within groups. You can get them out if you did something like *FQDN URL*/User(*user_id*)?$expand=Phones,Groups($expand=Rights)
This would give you the user, the phones they have, the groups they are in and the rights in those groups.

Other thing to note, the post request only has to include what you are wanting to change, so if you are not changing FirstName, LastName, EmailAddress or Number, you can just leave those out and just include {"Groups" : [*groups*]}

Do be careful with groups because if you do not pass in rights, it will default them to the user role

v20 API errors

mwiener1

stubh

spflug

stubh

paulodagraca

stubh

paulodagraca

stubh

DAndersonn@bis. itk

paulodagraca

stubh

DAndersonn@bis. itk

stubh

Latest Posts

Forum statistics

20 Years of VoIP
Industry Leadership

Company

Solutions

Useful Links

Learn More

v20 API errors

Forum statistics

20 Years of VoIP Industry Leadership

Company

Solutions

Useful Links

Learn More

20 Years of VoIP
Industry Leadership