Common Phone List Services¶

Create a Tenant’s common phone list entry¶

POST /api/v1/tenants/(string: tenant_id)/services/common_phone_list/¶

Create a new entry / new entries in the Common Phone List service of the Tenant.

Authorization Right:minimum Tenant Admin.

Example request:

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

{
   "entries": [
      {
         "name": "APIO Test Phone Number",
         "phoneNumber": "+32-12321312"
      },
      {
         "name": "Test Phone Number 2",
         "phoneNumber": "+32-32145698"
      }
   ]
}

Request JSON Object:

entries (array) – a list of objects as defined in Phone List attributes.

Status Codes:

200 OK – no error
404 Not Found – the service is not assigned to the Tenant
400 Bad Request – error during the creation

In case of creation of a single entry the answer body is the same as the GET intance, else it is the provided entries (done in this way to allow a afuture evoltuion of partial success if the AS behind the AIO supports it).

Display Tenant’s common phone list¶

GET /api/v1/tenants/(string: tenant_id)/services/common_phone_list/¶

Retrieve the entry list from the Common Phone List service of the Tenant.

Authorization Right:minimum End User.

Example request:

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

{
   "sensitiveNameStarts": "Test"
}

Response JSON Object:

combineWithOr (boolean) – See combineWithOr from Search criteria.
sensitiveNameStarts (string) – See sensitiveNameStarts from Search criteria.
sensitiveNameContains (string) – See sensitiveNameContains from Search criteria.
sensitiveNameEquals (string) – See sensitiveNameEquals from Search criteria.
insensitiveNameStarts (string) – See insensitiveNameStarts from Search criteria.
insensitiveNameContains (string) – See insensitiveNameContains from Search criteria.
insensitiveNameEquals (string) – See insensitiveNameEquals from Search criteria.
insensitivePhoneNumberStarts (string) – See insensitivePhoneNumberStarts from Search criteria.
insensitivePhoneNumberContains (string) – See insensitivePhoneNumberStarts from Search criteria.
insensitivePhoneNumberEquals (string) – See insensitivePhoneNumberStarts from Search criteria.
responseSizeLimit (integer) – See responseSizeLimit from Search criteria.

Example response:

HTTP/1.1 200 OK

{
   "entries": [
      {
         "name": "Test Phone Number 2",
         "phoneNumber": "+32-32145698"
      }
   ]
}

Response JSON Object:

entries (array) – a list of objects as defined in Phone List attributes.

Status Codes:

200 OK – no error
404 Not Found – the service is not assigned to the Tenant

Delete a Tenant’s common phone list entries¶

DELETE /api/v1/tenants/(string: tenant_id)/services/common_phone_list/¶

Delete an entry from the Common Phone List service of the Tenant.

Authorization Right:minimum Tenant Admin.

Example request:

DELETE /api/v1/tenants/foo/services/common_phone_list/ HTTP/1.1
Host: example.com

{
   "entries": [
      {
         "name": "APIO Test Phone Number"
      },
      {
         "name": "Test Phone Number 2"
      }
   ]
}

Request JSON Object:

entries (array) – a list of objects as defined in Phone List attributes.

Example response:

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

{}

Status Codes:

200 OK – no error
404 Not Found – the service is not assigned to the Tenant

Retrieve a Tenant’s common phone list entry¶

GET /api/v1/tenants/(string: tenant_id)/services/common_phone_list/(string: common_phone_name)/¶

Retrieve an entry in the Common Phone List service of the Tenant.

Authorization Right:minimum End User.

Example request:

GET /api/v1/tenants/foo/services/common_phone_list/APIO%20Test%20Phone%20Number/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "name": "APIO Test Phone Number",
   "phoneNumber": "+32-70321654"
}

Example response:

HTTP/1.1 200 OK

{}

Request JSON Object:

name (string) – See name from Phone List attributes.
phoneNumber (string) – See phoneNumber from Phone List attributes.

Status Codes:

200 OK – no error
404 Not Found – the entry was not found

Update a Tenant’s common phone list entry¶

PUT /api/v1/tenants/(string: tenant_id)/services/common_phone_list/(string: common_phone_name)/¶

Update an entry in the Common Phone List service of the Tenant.

Authorization Right:minimum Tenant Admin.

Example request:

PUT /api/v1/tenants/foo/services/common_phone_list/APIO%20Test%20Phone%20Number/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "name": "APIO Test Phone Number",
   "phoneNumber": "+32-70321654"
}

Example response:

HTTP/1.1 200 OK

{}

Request JSON Object:

name (string) – See name from Phone List attributes.
phoneNumber (string) – See phoneNumber from Phone List attributes.

Status Codes:

200 OK – no error
404 Not Found – the service is not assigned to the Tenant or the entry does not exist
400 Bad Request – error during the update

Delete a Tenant’s common phone list entry¶

DELETE /api/v1/tenants/(string: tenant_id)/services/common_phone_list/(string: common_phone_name)/¶

Delete an entry in the Common Phone List service of the Tenant.

Authorization Right:minimum Tenant Admin.

Example request:

DELETE /api/v1/tenants/foo/services/common_phone_list/APIO%20Test%20Phone%20Number/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

Example response:

HTTP/1.1 200 OK

{}

Status Codes:

200 OK – no error
404 Not Found – the entry does not exist

Create Update Delete Group’s common phone list entries with batch¶

POST /api/v1/tenants/(string: tenant_id)/services/common_phone_list/batch/¶

Create, updates or deletes entries in the Common Phone List service of the Tenant with batch processing of a CSV file.

Note:: The list of headers for the CSV file could be project specific.

The list of default headers are: Name, Phone Number, New Name

To create a new entry, insert a new line with Name, Phone Number columns
To modify the phone number, insert a line specifying Name and Phone Number columns, reporting the old name and the new phone number
To modify the name, insert a line specifying Name, Phone Number and New Name columns, reporting so the old name, the old phone number and the new name
To delete and entry, do not insert the entry in the file

Default delimiter: ;
Default quotechar: "
If the CSV file has no headers, has_header parameter MUST be sent as false

Note:

A CSV file is considered valid also for:

empty file
only headers row

Note:

A CSV file is considered invalid because of:

a wrong amount of columns
a wrong header names
does not respect constraints (could be project specific or ne specific)

Example request:

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

{
   "csv": "Base64EncodedString",
   "delimiter": ";",
   "quotechar": "'",
   "has_header": true
}

Example of a valid CSV file (only new entries):

Name;Phone Number
APIO Test Common Phone List Existing;+32-12345678
APIO Test Common Phone List New;+32-32165491
APIO Test Common Phone List New 2;+32-32165492
APIO Test Common Phone List New 3;+32-32165498

Example of a valid CSV file (modify phone numbers or name):

Name;Phone Number;New Name
APIO Test Common Phone List Existing;+32-12345678
APIO Test Common Phone List New;+32-70321654;APIO Test Common Phone List Modified
APIO Test Common Phone List New 2;+32-32165492
APIO Test Common Phone List New 3;+32-54987321

Example of a valid CSV file (entries to not delete):

Name;Phone Number
APIO Test Common Phone List Existing;+32-12345678

Request JSON Object:

csv (string) – the CSV file to upload, base64 encoded.
delimiter (string) – is the delimiter character for the CSV file (default: ;).
quotechar (string) – is the character to surround strings (default: ").
has_header (boolean) – if true, the first line of the CSV file will be treated has the header.

Example response:

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

{
   "results": [
      {
         "line": 1,
         "name": "APIO Test Common Phone List Existing",
         "phone_number": "+32-12345678",
         "status": "Success",
         "message": "Contact not modified"
      },
      {
         "line": "-",
         "name": "APIO Test Common Phone List to Delete",
         "status": "Success",
         "phone_number": "+32-70321654",
         "message": "Contact deleted"
      },
      {
         "line": 2,
         "name": "APIO Test Common Phone List New 2",
         "phone_number": "+32-32165492",
         "status": "Success",
         "message": "Contact added"
      }
      {
         "line": 3,
         "name": "APIO Test Common Phone List Modified 3",
         "phone_number": "+32-32165495",
         "status": "Success",
         "message": "Contact modified"
      }
   ]
}

Response JSON Object:

results (array) – the list of results: See Phonelist CSV Results.

Status Codes:

200 OK – full success
207 Multi Status – partial success
400 Bad Request – full failure or file invalid
404 Not Found – the service is not assigned to the user

Configuration Information for Batch Creation¶

The APIO behaviour is controlled by the following settings (same for all levels):

"PHONEBOOK_CSV_DEFAULT_HEADER" : ("Name", "Phone Number", "New Name"),
"PHONEBOOK_CSV_REQUIRED_HEADER": ("Name", "Phone Number"),
"PHONEBOOK_CSV_DELETE_MISSING": true,

With following parameters:

PHONEBOOK_CSV_DEFAULT_HEADER: The list of the expected headers when all fields are present, default is (“Name”, “Phone Number”, “New Name”)
PHONEBOOK_CSV_REQUIRED_HEADER: The list of the expected headers when only the mandatory fields are present, default is (“Name”, “Phone Number”)
PHONEBOOK_CSV_DELETE_MISSING: If True, all the contacts that are not in the csv file will be deleted. Default is False.