API sync on contact

You can configure an hookpoint url to your own application/software to make customer syncing possible at the moment your customer contacts your customer support. Your application must implement the following API interface in order for this to work.

The hookpoint URL you specified in the Omnidesk application will do a request on every contact. When making a request, Omnidesk will append additional query string parameters with an email address or a phone number. The URL that is configured can include a query string parameter like "key" for a key configured in your service that we verify before returning customer data (authentication).

For example, you can configure the following URL in omnidesk (Settings > Brands > CRM sync url):

https://api.brand.nl/omnidesk/customerlookup?key=xyzzy

And Omnidesk will construct one of the following types of URLs:

https://api.brand.nl/omnidesk/customerlookup?key=xyzzy&channelAddressType=phoneNumber&address=%2B31612312311&ticketID=1234
https://api.brand.nl/omnidesk/customerlookup?key=xyzzy&channelAddressType=email&address=thomas%40example.org&ticketID=1234

For phone number [phone] (use E.164 format), or email address [email protected].

New: it is now also possible to search based on the primary id in your system (klantnummer, ordernummer, etc). The response should contain the customer with that specific customer id. This should always result in zero or one result (not multiple since it is a primary id).

https://api.brand.nl/omnidesk/customerlookup?key=xyzzy&primaryID=42342345345

The response is JSON, always an array of results.

The resulting HTTP status code you should implement:

• 200 OK in case of success (even with empty result, i.e. if no customer information was found), with content-type "application/json; charset=utf-8".

• 400 Bad Request in case of missing query string parameters or malformed values.

• 500 Internal Server Error in case of errors.

• And other common HTTP errors if warranted.

The response result must look like this:

[
    {
        "addresses": [
            {
                "address": "[email protected]",
                "type": "email"
            },
            {
                "address": "[phone]",
                "type": "telephone"
            },
            {
                "address": "[phone]",
                "type": "telephone"
            },
            {
                "address": "1022334440541884",
                "type": "facebook"
            },
            {
                "address": "bird_223",
                "type": "twitter"
            }
        ],
        "customerFirstname": "M",
        "customerID": "2019000000000124",
        "customerLastname": "Lukkien",
        "customFields": [
           {"customerType": "unlimited"},
           {"customerSince": "2019-12-24"},
           {"favoriteColor": "orange"}        
        ],
        "timeline": [
           {
              "externalID": "2354rfwerf45",
              "lastUpdate": "2021-12-21 15:00:11",
              "type": "event",
              "message": "Marketing mail regarding price reduction",
              "source": "hubspot",
              "url": "https://hubspot.com/link234235"
           }
        ]
    }
]

Notes:

• In case no customer matches, an empty list "[]" is returned.

• The typical result is expected to have exactly one matching customer.

• If Omnidesk receives multiple customers in a response, it may choose to do nothing with the customers. Omnidesk will not just choose one of the hits. Omnidesk may be modified in the future to give customer service agents a list of customers to select from.

• It is possible to whitelist Omnidesk IP('s) for your interface. Please contact us for the IP's to whitelist.