Terminology

The term client is used to identify people-related clients or partners that perform integration with the peoplefone CONNECTOR.

The term phone lookup service is used to identify the service of the client that makes the current interface available for the peoplefone CONNECTOR to collect data.

Overview

The peoplefone CONNECTOR API covers several use cases:

Data search for notification purposes
- When a phone call is executed (incoming or outgoing), peoplefone HOSTED notifies peoplefone CONNECTOR, which searches for data using the REST API described in this article.

Interaction with the business workflow
- When the peoplefone CONNECTOR user clicks on one of the business workflows, the peoplefone CONNECTOR user transfers the request to the phone lookup service for handling. The business workflow can include creating a ticket or a call history in CRM.

Part 1 – Data Query

Request

URL

https://clientServiceAddress/someController

The request URL is defined by the client so that peoplefone CONNECTOR can reach the phone search service. This URL does NOT contain any private data that is required for the search. This data is provided via HTTP header.

Query parameters

peoplefone CONNECTOR gibt die Telefonnummer über den folgenden Abfrage-Parameter an:

Schlüssel: Telefonnummer
Wert (sample): 4178907228
https://clientServiceAddress/someController?PhoneNumber=4178907228

HTTP-Header

For authentication peoplefone CONNECTOR provides a token via the following HTTP header:

Schüssel: X-Execution-Token
Wert: jlvlkdshvövdjhwgjwogjhwg

Body

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

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

Reply

Example from HTTP 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 objects. It is recommended to return only a very small number of results. The value of maximum 5 results is best for a balance between performance and precision. However, increasing this value can cause significant delays and performance problems at all stages of the system.

If the query does not return a value, peoplefone CONNECTOR is expected to receive an empty array with a status code of 200. In this case NO 404 status code is expected. The 404 status code means that the phone search service cannot be accessed.

Layer 2: The object

The objects that make up the list represent an entry found for the specified phone number in the integrated CRM. This object contains only few fields that are required for peoplefone CONNECTOR to properly display the entry, as well as a list of key-value pairs for certain data that our client wants to add.

Field name	Description
Name	The full name of the contact found. This is used in the user interface to display the name of the contact.
Company	The name of the company the contact is associated with. This is used in the user interface to display the name of the company.
ContactUri	The URI to access the contact page in CRM. This is used in the user interface to connect to the contact.
CompanyUri	The URI to access the company page in CRM. This is used in the user interface to connect to the company.
Id	The ID of the contact in CRM. This value is not displayed.\|
CrmName	The name of the CRM. This value, if specified, is used to add a tooltip to the CRM logo.me des CRM. This value, if specified, is used to add a tooltip to the CRM logo.
CrmLogo	The URL of the CRM’s logo. This value, if specified, will be used to add a logo to the contact card for this entry. This is optional if the customer has only one CRM integration. However, it becomes useful if the customer has multiple CRM integrations.
CustomFields	The CustomFields object is a set of key-value pairs that allows the client to transfer all the data they need for the.

Teil 2 – Geschäftsablauf

Request

URL

<root-url>/<workflow-name>
The <root-url> is the same value as in the search (see part 1). This is the name returned by the search in the CrmActions array.

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

Zur Anzeige des Business-Workflows auf der peoplefone CONNECTOR Webseite. Für einige vordefinierte Werte wird er übersetzt, ansonsten wird er AS-IS angezeigt.

Für die automatische Konfiguration von Geschäftsabläufen. Im Moment kann nur der Business-Workflow “CallFlow” im peoplefone CUSTOMER-PORTAL automatisch konfiguriert werden, alle anderen Fälle werden nur manuell eingestellt.

Query parameters

peoplefone CONNECTOR does not provide query parameters

HTTP Headers

For authentication peoplefone CONNECTOR provides the same headers as for search, as configured on the peoplefone CUSTOMER-PORTAL page.

Body

The main part of the request contains all the necessary information for the business process to be executed. This payload could be extended in the future. It is an “inputs” field that contains 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":"...",
        ...
    }
}

Reply

The response expected from peoplefone CONNECTOR is a simple JSON object with two fields, where the whole response and the individual fields are optional. The purpose of the URL is to optionally open the CRM page directly after the workflow is finished.

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":"..."
}

Performance Issues

The response time is essential to allow the user to see, as soon as possible, the relevant information in the peoplefone CONNECTOR application.

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

peoplefone CONNECTOR API (REST API)

Terminology

Overview

Part 1 – Data Query

Request

URL

Query parameters

HTTP-Header

Body

Reply

Layer 1: The List

Layer 2: The object

Teil 2 – Geschäftsablauf

Request

URL

Query parameters

HTTP Headers

Body

Reply

Performance Issues