OkCollect Webhook

This webhook allows log user interactions with their OkHi address enabling you to get rich data insights from OkHi.

Create an address interaction

POST https://sandbox-api.okhi.io/v5/interactions

Headers

Name	Type	Description
Authorization*	string	Authenticate to the OkHi API by sending your branch ID and server key along with a request. Authentication is by passing a header value of base64 encoding of branchId:serverKey prepended with the string "Token " to the Authorization property. In practice that means taking your branch ID, eg if your branch id is abc adding a colon, and then appending your server key to it, eg, if your server key is xyz. After base64 encoding abc:xyz becomes YWJjOnh5eg==; and this is passed in the authorization header like so: Authorization: Token YWJjOnh5eg==.

Request Body

Name	Type	Description
user	string	OkHi user object, see example below
value	number	eg. for a checkout this could be the order amount
id	string	A unique order ID
use_case*	string	for loans this could be "loan". For e-commerce this could be: "e-commerce"
location_id	string	OkHi location ID
location	object	OkHi location object would be required if you don't have a location ID. See example below
properties	object	This is an open field where you can put any business related information related to the interaction for use in analysis later. See an example below.

201 Interaction created successfully.

{
    "success": true
}

400

{
    "code": 400,
    "message": "Specify either a location ID or a location object"
}

If you don't supply a locationId then the user & location parameters are required

Properties Object

A dictionary of information that provides useful details to a given address interaction relevant to your business.

All fields except the ones listed in the table below are open to you to design to suit your business.

Field	Type	Description
send_to_queue	boolean	Mostly used in e-commerce. Set to true in order to push the checkout details to OkHi Queue app for dispatch management
payment_method	string	Mode of payment used in a checkout context
dates	date	All dates should be in ISO 8601 format
brand	string	Your brand name in one word, all lowercase eg acme
location	string	The outlet location in one word, all lowercase eg. thehub
value	float	A numeric value associated with the interaction, eg. total basket value
currency	string	Currency code in ISO 4217 format

Here's an example of a properties JSON object that you could have in a checkout context:

Properties Object

{
  "brand": "acme",
  "branch": "thehub",
  "payment_method": "cash",
  "currency": "KES",
  "send_to_queue": true,
  "basket": [
    {
      "sku": "RF67DESL1/XFA",
      "value": 180000.00,
      "name": "RF67DESL FDR with Twin Cooling Plus, 491 L",
      "description": "Refrigerator is designed to improve the way you store food through an innovative 2-Door system.",
  	  "category" : "fridge",
      "quantity": 1
    },
    {
      "sku": "MG28J5255GS/SM",
      "value": 5500.00,
      "name": "MW5200J Grill Microwave Oven with Healthy Steam, 28 L",
      "description": "Enjoy the flexibility to bake and microwave – all from one appliance",
      "category": "microwave ovens",
      "quantity": 1,
      "weight": 1.2
    }
  ],
  "shipping": {
    "cost": 120.00,
    "class": "Flat rate",
    "expectedDeliveryDate": "2019-08-12T09:42:22.526Z"
  }
}

User Object

This is only required if you don't have an OkHi location ID

OkHi User object

{
    "firstName": "Bob",
    "lastName": "Mark",
    "phone": "[phone]"
}

Location Object

This is only required if you do not have an OkHi location Id.

You must supply at least one of these fields: a street name, property name, directions, placeId(from OkHi), lat & lng

Field	Type	Description
property_name	string	Building name eg. Riverside Villas
property_number	string	Building number eg 12
street_name	string	Street name eg. Peponi Road
lat	float	Latitude eg. -1.21231
lng	float	Longitude eg. 35.123123
place_id	string	OkHi place ID that refers to a unique common address in our database
directions	string	Take a left where the goats used to graze
other_information	string	Useful instructions of how get to the door eg. Call the askari on 072112...
business_name	string	Business name eg. ACME LTD
unit	string	Unit identifier eg. APT 12A
floor	string	Floor number

An example of an OkHi location JSON object, only required if you don't have a location ID

OkHi Location Object

{
        "lat": -1.2489607,
        "lng": 36.7521819,
        "place_id": "LKjs8YA7",
        "street_name": "Loresho Close",
        "property_name": "Park Villas"
}

Full example payload for an ecommerce transaction:

{
    "id": "{{uniqueTransactionId}}",
    "use_case": "e-commerce",
    "location_id": "WtyVrLr3yn",
    "value": 185500,
    "user": {
        "first_name": "E",
        "last_name": "M",
        "phone": "[phone]"
    },
    "properties": {
        "brand": "acme",
        "branch": "thehub",
        "payment_method": "cash",
        "send_to_queue": true,
        "basket": [
            {
                "sku": "RF67DESL1/XFA",
                "value": 180000,
                "name": "RF67DESL FDR with Twin Cooling Plus, 491 L",
                "description": "Refrigerator is designed to improve the way you store food through an innovative 2-Door system.",
                "category": "fridge",
                "quantity": 1
            },
            {
                "sku": "MG28J5255GS/SM",
                "value": 5500,
                "name": "MW5200J Grill Microwave Oven with Healthy Steam, 28 L",
                "description": "Enjoy the flexibility to bake and microwave – all from one appliance",
                "category": "microwave ovens",
                "quantity": 1,
                "weight": "1 kg"
            }
        ],
        "shipping": {
            "cost": 120,
            "class": "Flat rate",
            "expected_delivery_date": "2019-08-12T09:42:22.526Z"
        }
    }
}

IMPORTANT: For production please switch this endpoint to https://api.okhi.io/v5/interactions