Numbers¶

List numbers¶

GET /api/v1/tenants/(string: tenant_id)/numbers/¶

List the numbers owned by the Tenant that are in available state (meaning not yet assigned to a Group) and or the status of all phone numbers (assigned to a Group or not)

Example request:

GET /api/v1/tenants/foo/numbers/ HTTP/1.1
Host: example.com

{
   "available": true,
   "assignement": true
}

Request JSON Object:

available (boolean) – indicate if the list of available numbers must be returned.
assignement (boolean) – indicate if the list of numbers with their assigned Group must be returned.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "assignement_phoneNumbers": [
      {"phoneNumber": "+3225126789", "canBeDeleted": true, "assignedToGroup": ""},
      {"phoneNumber": "+3225126999", "canBeDeleted": true, "assignedToGroup": ""},
      {"phoneNumbers": "+3226127000 - +3226127002", "canBeDeleted": true, "assignedToGroup": ""},
      {"phoneNumber": "+3225126997", "canBeDeleted": false, "assignedToGroup": "fooGroup"}
   ],
   "available_phoneNumbers": [
      {"phoneNumber": "+3225126789"},
      {"phoneNumber": "+3225126999"},
      {"phoneNumbers": "+3226127000 - +3226127002"},
   ]
}

Note

In case none of the input parameters is provided, assignement_phoneNumbers is returned.

In case both parameters are set to False, assignement_phoneNumbers and/or available_phoneNumbers are returned as empty lists.

Response JSON Object:

available_phoneNumbers (array) – a list of numbers or range of numbers that are available for assignement (meaning not assigned to a Group). See Available PhoneNumber(s)
assignement_phoneNumbers (array) – a list of numbers or range of numbers (phoneNumbers) with the indication of the Group they are assigned to if any (assignedToGroup) and if they can be deleted canBeDeleted). See Assignement Status of PhoneNumber(s)

Status Codes:

200 OK – no error

Add numbers¶

POST /api/v1/tenants/(string: tenant_id)/numbers/¶

Add a list or a range of numbers in the tenant. They will be in ‘available’ state.

Example request:

POST /api/v1/tenants/foo/numbers/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "numbers": [
      {"phoneNumber": "021234567"},
      {"phoneNumber": "041234567"}
   ],
   "range": {
      "minPhoneNumber": "071568000",
      "maxPhoneNumber": "071568002"
   }
}

Request JSON Object:

numbers (array) – the list of numbers to be added.
range (array) – the range of numbers to be added as a list of 2 numbers (start and end).

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "result": [
      {"phoneNumber": "021234567", "status": "added"},
      {"phoneNumber": "041234567", "status": "rejected"}
      {"phoneNumber": "071568000", "status": "added"},
      {"phoneNumber": "071568001", "status": "added"},
      {"phoneNumber": "071568002", "status": "added"}
   ]
}

Response JSON Object:

result (array) – a list of objects containing at least the number and it’s status (‘added’, ‘rejected’, ‘available’). See Tenant Numbers result items. The ranges as splitted into individual numbers in this report.

Status Codes:

201 Created – no error
207 Multi Status – partial success
400 Bad Request – full error. This could cover two cases : error reported during the validation of the data (in that case it is following the usual error structure Error messages) or all the numbers rejected by the System provisioned by APIO (in that case with a result” structure).

Most frequent validation errors:

2 (INVALID_PARAMETERS) : some numbers provided are not valid numbers
9 (MISSING_CONDITIONAL_PARAMETERS): a range structure was provided but it can not be translated into individual numbers

Remove numbers¶

DELETE /api/v1/tenants/(string: tenant)/numbers/¶

Delete a list or a range of numbers in the tenant.

Example request:

DELETE /api/v1/tenants/foo/numbers/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "numbers": [
      {"phoneNumber": "021234567"},
      {"phoneNumber": "041234567"}
   ]
}

Request JSON Object:

numbers (array) – the list of numbers to be removed.
range (array) – the range of numbers to be removed as a list of 2 numbers (start and end).

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}

Status Codes:

200 OK – no error
207 Multi Status – partial success
400 Bad Request – full error

Tenant Numbers result items¶

Name	Type	Description
phoneNumber	String	The phone number.
status	Boolean	The resulting status of the operation, each API will indicate what status are possible.
message	String	An optional message providing more information about the status of the operation on the number
code	String	An error code if the operation has failed. See Error messages.
details	String	An error details if the operation has failed. See Error messages.

Possible values for the status¶

The following values could be returned in case of POST operation:

added : number added to this Tenant
available : This number was already assigned to this Tenant and not assigned to any lower entity. This is considered asd a success
rejected : This number can not be added to this Tenant (mainly due to: owned by an other Tenant, not valid, own by this Tenant and already assigned to a sub-entity)

Possible values for the message¶

The following values could be returned for the message (this is an information field so it could vary over the time to report more precise messages):

Not yet assigned to any Group. : Usually linked to status available
Already assigned to Group {group_id}. : Usually linked to status rejected
Already assigned to Tenant {tenant_id}. : Usually linked to status rejected