peoplefone CONNECTOR API (REST API)

Terminology

Client is used to identify peoplefone customer or partner that does the integration with the peoplefone CONNECTOR

Phone lookup service is used to identify the client’s service that exposes the current interface for the peoplefone CONNECTOR to acquire data.

When can the peoplefone CONNECTOR API be used?

If the client’s CRM is not supported by peoplefone, we ask the client to provide a phone lookup service.

Overview

The API covers multiple use-cases:

1. Data lookup for notification purpose
   When a phone call is performed (incoming or outgoing) the peoplefone HOSTED will notify the peoplefone CONNECTOR which will lookup for data using the REST API described in this article.
2. Business workflow interaction
   When the peoplefone CONNECTOR user click on one of the business workflow, the peoplefone CONNECTOR will transfer the request to the phone lookup service for treatment. Business workflow could be anything like creating a ticket or a call flow in the CRM.

Note: only the part 1 is treated atm, part 2 is still under construction.

Part 1 – data lookup

Request

URL

https://clientServiceAddress/someController
The request URL is defined by the Client to allow peoplefone CONNECTOR to reach the phone lookup service. This URL does NOT contains any private data required for the lookup, those data are provided via HTTP Headers.

Query parameters

peoplefone CONNECTOR shall provide the phone number via the following query parameter:
Key: PhoneNumber
Value (sample): 4178907228
https://clientServiceAddress/someController?PhoneNumber=4178907228

HTTP Headers

For authentication, peoplefone CONNECTOR shall provide the token via the following HTTP Header:
Key: X-Execution-Token
Value: jlvlkdshvövdjhwgjwogjhwg

Body

The body of the request is, for the time being, not used by the peoplefone CONNECTOR

Response

Sample of body

[
   {
      "Name": "Alexa Holiday",
      "Company": "White Cross Co",
      "ContactUri": "https://...",
      "CompanyUri": "https://...",
      "Id": "Crm Identification Number",
      "CrmName": "Sugar CRM",
      "CrmLogo": "https://...",
      "CustomData": {
         "Title1": "Data1", 
         "Title2": "Data2"
      }
   },
   {
      ...
   }
]

Layer 1: the list

The expected result is an array of object. It is recommended to return only a very small number of results. The value of maximum 5 results is the most suitable for a good balance between performance and precision. However increasing this value could end with a lot of delay and performance issue at all stage of the system.

If the query does return no value, it is expected by peoplefone CONNECTOR to receive an empty array with a 200 status code. It is NOT expected to receive a 404 status code in that case, the 404 status code will means the Phone lookup service is not accessible.

Layer 2: the object

The objects composing the list represent one entry found for the given phone number in (one of) the integrated CRM. This object contains few fields required for peoplefone CONNECTOR to display properly the entry as well as a list of key-value pairs for any specific data our customer want to add.

Field Name	Description
Name	The full name of the found contact. This is used in the user interface to display the name of the contact.
Company	The name of the company on which the contact is linked to. This is used in the user interface to display the name of the company.
ContactUri	The URI to access the contact page on the CRM. This is used in the user interface to add a link to the contact.
CompanyUri	The URI to access the company page on the CRM. This is used in the user interface to add a linke to the company.
Id	The Id of the contact in the CRM. This value is not displayed.
CrmName	The name of the CRM. This value, if provided, is used to add a tooltip on the CRM logo.
CrmLogo	The URL of the logo of the CRM. This value, if provided, is used to add a logo on the contact card for this entry. This is optional if the customer integrate only with one CRM. However it become useful if the customer has multiple CRM integration.
CustomFields	The object CustomFields is a set of key-value pairs the customer can use to carry any data he needs for the integration. Those data, if present, will be displayed in the peoplefone CONNECTOR user interface. It could be for instance the e-mail address of the contact or the language spoken by the contact or anything else.

Part 2 – Business workflow

Will follow soon

Performance concerns

The response time is key to allow the user to see as soon as possible the appropriate information in the peoplefone CONNECTOR application.

The phone lookup service must be as fast as possible to ensure a short response time for the peoplefone CONNECTOR user. If however the phone lookup service should answer too slowly the peoplefone CONNECTOR will send a timeout and answer basic information to the user (phone number and call status with the name “unknown”).