Personal Phone List Services

Create a User’s personal phone list entry

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/

Create a new entry / new entries in the Personal Phone List service of the user.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_phone_list/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "entries": [
      {
         "name": "APIO Test Phone Number",
         "phoneNumber": "+32-12345678"
      },
      {
         "name": "Test Phone Number 2",
         "phoneNumber": "+32-32165491"
      }
   ]
}
Request JSON Object:
Status Codes:

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 User’s personal phone list

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/

Retrieve the entry list from the Personal Phone List service of the user.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_phone_list/ HTTP/1.1
Host: example.com

{
   "sensitiveNameStarts": "Test"
}

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_phone_list/ HTTP/1.1
Host: example.com

{
   "sensitiveNameStarts": "Test",
   "pagingControl" : {
      "startIndex" : 1,
      "pageSize" : 2
   },
   "sortOrders": ["sensitiveAscendingNumber"]
}
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 insensitivePhoneNumberContains from Search criteria.

  • insensitivePhoneNumberEquals (string) – See insensitivePhoneNumberEquals from Search criteria.

  • responseSizeLimit (integer) – See responseSizeLimit from Search criteria.

Request JSON Object:

  • pagingControl (object) – (Optional) See pagingControl from Paging Control elements. If pagingControl is provided, responseSizeLimit will be ignored.

  • sortOrders (array) – (Optional) See sortOrders from Paging Control elements. Maximum 1 element in the list. Possible field names are : “Name” and “Number”. Default is “insensitiveAscendingName”.

Example response:

HTTP/1.1 200 OK

{
   "entries": [
      {
         "name": "Test Phone Number 2",
         "phoneNumber": "+32-32165491"
      }
   ]
}
Response JSON Object:
Status Codes:

Delete a User’s personal phone list entries

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/

Delete an entry from the Personal Phone List service of the user.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_phone_list/ HTTP/1.1
Host: example.com

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

Example response:

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

{}
Status Codes:

Retrieve a User’s personal phone list entry

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/(string: personal_phone_name)/

Retrieve an entry in the Personal Phone List service of the user.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_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:
Status Codes:

Update a User’s personal phone list entry

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/(string: personal_phone_name)/

Update an entry in the Personal Phone List service of the user.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_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:
Status Codes:

Delete a User’s personal phone list entry

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/(string: personal_phone_name)/

Delete an entry in the Personal Phone List service of the user.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/services/personal_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:

Create Update Delete User’s personal phone list entries with batch

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/personal_phone_list/batch/

Create, updates or deletes entries in the Personal Phone List service of the user batch processing 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/groups/foogroup/users/foouser/services/personal_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 Personal Phone List Existing;+32-12345678
APIO Test Personal Phone List New;+32-32165491
APIO Test Personal Phone List New 2;+32-32165492
APIO Test Personal Phone List New 3;+32-32165498

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

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

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

Name;Phone Number
APIO Test Personal 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 Personal Phone List Existing",
         "phone_number": "+32-12345678",
         "status": "Success",
         "message": "Contact not modified"
      },
      {
         "line": "-",
         "name": "APIO Test Personal Phone List to Delete",
         "status": "Success",
         "phone_number": "+32-70321654",
         "message": "Contact deleted"
      },
      {
         "line": 2,
         "name": "APIO Test Personal Phone List New 2",
         "phone_number": "+32-32165492",
         "status": "Success",
         "message": "Contact added"
      }
      {
         "line": 3,
         "name": "APIO Test Personal Phone List Modified 3",
         "phone_number": "+32-32165495",
         "status": "Success",
         "message": "Contact modified"
      }
   ]
}
Response JSON Object:
Status Codes:

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.