Menu Close



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.


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




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


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

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


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

    "inputs": {


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 nameDescription
NameThe full name of the contact found. This is used in the user interface to display the name of the contact.
CompanyThe name of the company the contact is associated with. This is used in the user interface to display the name of the company.
ContactUriThe URI to access the contact page in CRM. This is used in the user interface to connect to the contact.
CompanyUriThe URI to access the company page in CRM. This is used in the user interface to connect to the company.
IdThe ID of the contact in CRM. This value is not displayed.|
CrmNameThe name of the CRM. This value, if specified, is used to add a tooltip to the CRM des CRM. This value, if specified, is used to add a tooltip to the CRM logo.
CrmLogoThe 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.
CustomFieldsThe 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



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.


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 NameDescription
contactCrmIdThe ID of the contact in the CRM (as retrieved from the lookup)
userCrmIdThe ID of the user linked to the current SIP user (as configured in the CUSTOMER-PORTAL page)
originatorNumberThe phone number that initiated the call.
originatorNameWhen available the name of the person who initiated the call.
destinationNumberThe phone number composed by the caller.
destinationNameWhen available the name of the person which answer the call.
directionThe direction of the call, either ‘incoming’ or ‘outgoing’.
startedTimeThe date/time when the call was started (ringing).
answeredTimeThe date/time when the call was answered, this value is empty if the call was not answered.
endedTimeThe date/time when the call was ended.
declinedTimeThe date/time when the call was aborted, this value is empty if the call was answered.
idThe id returned by the CRM on the previous workflow request (for the same call), null in case it is the first request
    "inputs": {


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 NameDescription
idThe ID of the object created by the business workflow
urlThe URL to access the object created by the business workflow

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