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.

Overview

The API covers multiple use-cases:

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.
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.

Part 1 – data lookup

Request

URL

<root-url>/Lookup (example: https://my-company.com/services/Lookup)
The <root-url> is defined by the Client in the peoplefone CUSTOMER-PORTAL 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. The name of the end-point for the lookup capabilities must be called Lookup.

Query parameters

peoplefone CONNECTOR will not provide query parameters

HTTP Headers

For authentication, peoplefone CONNECTOR shall provide the token via the following HTTP Header:
Key: X-Execution-Token
Value: jlvlkdshvövdjhwgjwogjhwg
The header(s) key and value are configurable though the peoplefone PORTAL page regarding peoplefone CONNECTOR

Body

The body of the request is contains the phone number for which the lookup is required:

  {
    "inputs": {
        "phoneNumber":"41215522000"
    }
}

Response

Sample of body

[
   {
      "name": "Alexa Holiday",
      "company": "White Cross Co",
      "contactUri": "https://...",
      "companyUri": "https://...",
      "id": "Crm Identification Number",
      "crmName": "Sugar CRM",
      "crmLogo": "https://...",
      "crmActions":["CallFlow"],
      "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.
crmActions	This is a list of string, each string being the name of the available workflow that is applicable to this contact. This name will be used to drive the whole business workflow capabilities (more information on the second part of the API).
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

Request

URL

<root-url>/<workflow-name>
The <root-url> is the same value than for the lookup (see part 1). The <workflow-name> is the name given back by the lookup in the CrmActions array.

The <workflow-name> is relatively free to use, however the value is used to two other places outside the peoplefone CONNECTOR API definition:

To display the business workflow in the peoplefone CONNECTOR web page. For some predefined values it will be translated, otherwise it will be displayed AS-IS.
For automatic business workflow configuration. At the moment only business workflow called “CallFlow” can be configured in the peoplefone CUSTOMER-PORTAL to be set automatic, all other cases will be manual only.

Query parameters

peoplefone CONNECTOR will provide no query parameters

HTTP Headers

For authentication, peoplefone CONNECTOR will provide the same headers than for the lookup, as configured in the peoplefone CUSTOMER-PORTAL page.

Body

The body of the request contains all required information for the business workflow to be executed. This payload could be extended in the future. It is an “inputs” field containing a simple JSON object with the following fields:

Field Name	Description
contactCrmId	The ID of the contact in the CRM (as retrieved from the lookup)
userCrmId	The ID of the user linked to the current SIP user (as configured in the CUSTOMER-PORTAL page)
originatorNumber	The phone number that initiated the call.
originatorName	When available the name of the person who initiated the call.
destinationNumber	The phone number composed by the caller.
destinationName	When available the name of the person which answer the call.
direction	The direction of the call, either ‘incoming’ or ‘outgoing’.
startedTime	The date/time when the call was started (ringing).
answeredTime	The date/time when the call was answered, this value is empty if the call was not answered.
endedTime	The date/time when the call was ended.
declinedTime	The date/time when the call was aborted, this value is empty if the call was answered.
id	The id returned by the CRM on the previous workflow request (for the same call), null in case it is the first request

{
    "inputs": {
        "contactCrmId":"...",
        "userCrmId":"...",
        ...
    }
}

Response

The response expected by peoplefone CONNECTOR is a simple JSON object with two fields, the whole response, as well as each fields, are optional. The purpose of the url would be to optionally open the CRM page directly after the workflow is ended.

Field Name	Description
id	The ID of the object created by the business workflow
url	The URL to access the object created by the business workflow

{
    "id":"...",
    "url":"..."
}