Create Customer from Lead with IP Group (Advanced Configuration)

This request enables you to create a new customer from a lead by creating an IP Group and Proxy Set on the OnlinePstnGateway (AudioCodes SBC device configured to connect calls between PSTN trunk and Microsoft Teams) device and creating a link between Live Platform portal database and the SBC device using the newly created IP Group.

IP Groups are mandatory for SIP Registration. This request is applied in the Live Platform portal in the Advanced tab when changing status of the lead (see Enabling Operator Connect License).

URI

Copy 
{{baseUrl}}/api/v3/customer

HTTP Method

POST

Request Body

Parameter

Type

Description

ConfigurationName

string
■ OcEssential_IPGROUP_TYPE: An IP Group is created for each new customer based on the Customer Shortname. This type is used for the Access Trunk Direct Routing (used for Direct Routing customers when SIP Registration is required). An link is established with the Live Platform server (OVOC) using this IP group.

shortName

string

Short customer name, complying with validation rules for customer name:

■ The string should be 3-15 characters long
■ The following characters cannot be used: \ / : * ? " < > |audit
■ Can contain letters (lower/UPPER case), Numbers and special characters are allowed, however cannot contain the dot (.) or blank spaces.
■ Unique name per M365 Tenant

CustomerFulName

string

Generally the company name, however, any value can be used.

msTenantID

string

The Microsoft Azure subscription Tenant Id of the customer lead.

scriptParameters

list array

List array including the following values:

■ ProxySet (SBC carrier)
■ OnlinePstnGateway
■ Custom Variables

ProxySet (SBC carrier)

string

SBC Proxy Set to apply to the PSTN gateway. The same Proxy set and Proxy Address can be used for multiple customers.

OnlinePstnGateway

string

Online PSTN gateway (SBC device connected to Live Cloud and activated on Micrsosoft, see 'Get Online PSTN Gateway').

Custom Variables

string

Custom variables configured for the script. For example, IP-PBX credentials.

Example Request Body

Copy 
{
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "customerShortName": "SIPTest4",
  "customerFullName": "SIPTest4",
  "msTenantId": "f79a7f93-5ef7-47d2-92c8-e4570503cec3",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}
}

Example Response

The initial response displays the Task Id.

Parameter

Type

Description

Task Id

string

The queued task Id that is generated for this action. You must run the Task request to retrieve the status of the action. See Task Status. Note that the wst string in the prefix is unique for this endpoint.
Copy 
{
    "taskId": "wst_1a93b0c9-5ab0-4d3f-af25-c0f18ad0aa2e"
}

The execution of the request may take a few minutes. The status will progress from 'In Progress' to 'Completed Success'.

Copy 
{
    "id": "wst_9a7ff916-aab2-41d1-a9fe-0e9baacf4a15",
    "status": "CompletedSuccess",
    "details": [
        "Converted"
    ],
    "executionMessages": [
        {
            "level": "Information",
            "message": "SBC sbc-onboarding done for site SIPTest4."
        },
        {
            "level": "Information",
            "message": "Site created in Ovoc"
        }
    ],
    "outputData": {
        "umpCustomerGuid": "1b9ec2ad-bf3e-4096-b387-9daa05750616"
    },
    "createTime": "0001-01-01T00:00:00"
}

HTTP Responses

■ 200 OK

Parameter

Type

Description

id

string

Task Id

status

string

One of the following values:

■ In Progress
■ Completed Success
■ Completed Failed

details

string

One of the following values:

■ Converted

executionMessages

list array

List array including the following parameters:

■ level
■ message

level

string

One of the following values:

■ Information
■ Error

message

string

Example error messages are described below.

■ The following Request body includes a customer name with more than 15 characters:
Copy 
{
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "customerShortName": "SIPTest4abc12345",
  "customerFullName":  "SIPTest4abc12345",
  "msTenantId": "f79a7f93-5ef7-47d2-92c8-e4570503cec3",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}
}
✔ As a result, the following error is displayed in the output of the Get Task Id request):
Copy 
{
    "id": "wst_b5680a28-f831-4fcf-a6bb-7edeeb616602",
    "status": "CompletedFailed",
    "details": [
        "Failed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "'Customer Short Name' must be between 3 and 15 characters."
        }
    ],
    "outputData": {
        "umpCustomerGuid": null
    },
    "createTime": "0001-01-01T00:00:00"
}
■ The following Request body includes an invalid character ".":
Copy 
 {
  "configurationName": "OcEssential_IPGROUP_TYPE",
  "customerShortName": "SIPTest4-",
  "customerFullName":  "SIPTest4-",
  "msTenantId": "f79a7f93-5ef7-47d2-92c8-e4570503cec3",
  "scriptParameters": {
    "ProxySet": "SIPTrunk",
    "OnlinePstnGateway":"oc1.sandbox2.audiocodes.be"}
}
✔ As a result, the following error is displayed in the output of the Get Task Id request:
Copy 
{
    "id": "wst_1835f515-374c-49de-a3be-c2fb8f4ef248",
    "status": "CompletedFailed",
    "details": [
        "Failed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Customer Short Name contains invalid characters. Allowed characters: letters, numbers and '_'."
        },
        {
            "level": "Error",
            "message": "Customer Full Name contains invalid characters. Allowed characters: letters, numbers, _, ' and space."
        }
    ],
    "outputData": {
        "umpCustomerGuid": null
    },
    "createTime": "0001-01-01T00:00:00"
}

The following error is displayed when there is no active lead:

Copy 
{
    "id": "wup_4f54e857-f68a-4743-ac8e-07d13ec09abc",
    "status": "CompletedFailed",
    "details": [
        "ValidationFailed"
    ],
    "executionMessages": [
        {
            "level": "Error",
            "message": "Validation failed: Empty or invalid customer lead ID"
        },
        {
            "level": "Information",
            "message": "Workflow completed."
        }
    ],
    "outputData": {
        "createTime": "2024-04-16T11:58:36.6745335Z",
        "completeTime": "2024-04-16T11:58:40.9251167Z",
        "ocUploadNumberResult": "ValidationFailed",
        "workflowVersion": 3,
        "msJobStatus": ""
    },
    "createTime": "0001-01-01T00:00:00"
}

The following error is displayed when a customer has already been created for the tenant:

Copy 
{
    "id": "wst_0925d9d6-a8aa-418e-aeac-95f7a7f2e815",
    "status": "CompletedSuccess",
    "details": [
        "CustomerAlreadyConverted"
    ],
    "executionMessages": [
        {
            "level": "Warning",
            "message": "Undo Lead to OcBasic conversion in database!"
        }
    ],
    "outputData": {
        "umpCustomerGuid": null
    },
    "createTime": "0001-01-01T00:00:00"
}

umpCustomerGuid

string($uuid)

This id is created in the Live Platform database for the customer tenant when a Live Platform license is applied. If this field is null, a license has not yet been applied to the lead.

This value is also obtained in the 'Get Task' response when the customer is created.

outputData

list array

Additional information.