Kulea REST API - Developer Guide

Introduction

The Kulea Application Programming Interface (API) allows third-party systems to integrate with Kulea.  The API follows the REST protocol and will require an authorization key provided to you by Kulea.  This guide is intended for a technical audience such as developers and webmasters. 

Authorisation

Kulea uses API keys to allow authorised access to its API.  You can request your API key by contacting Kulea at contacts@kulea.ma

All REST API requests can be authenticated by having the following Authorization header in each request:

  • Set header field "Authorization={Kulea API Key}"

Any problems then do get in touch at contact@kulea.ma

REST API Guide

 

Definition

Describes the fields associated with Kulea Contact records along with its type.

REST AP URL 

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • reason - only shown if success is false and indicates the reason of failure.
  • count - represents the total number of fields associated with a Kulea contact
  • fields- jsonArray representation of each field in a Kulea contact

Example:

{
    "success": true,
    "count": 5,
    "fields": [
        {
            "fieldname": "date created",
            "type": "Date"
        },
        {
            "fieldname": "email",
            "type": "Text"
        },
        {
            "fieldname": "forename",
            "type": "Text"
        },
        {
            "fieldname": "signupdate",
            "type": "Text"
        },
        {
            "fieldname": "surname",
            "type": "Text"
        }
    ]
}

Definition

Returns a list of Kulea Contacts. This list can be filtered so that you can search against different fields.

REST API URL

Example URL 

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Query String

The presence of a query string parameters will allow contacts to be filtered accordingly.  The list of query string parameters available are:

  • dtfrom and dtto: allow you to filter between dates when the contact records were created e.g. dtfrom=20170201-133212, will search for all records created after 01/02/2017 13:32:12.
  • filter1...filterN: allows you to filter based on comparing fields e.g. surname:ct:gates, will search for all records where the 'surname' field contains (ct) 'gates'.
  • fields: allows you to only retrieve the fields specified in the resulting response e.g. fields=email,surname,forename will only return the three fields in the response
  • start: start index of where search needs to start from
  • count: number of records to return
  • only_archived: only return archived records if set to true (otherwise returns both archived & unarchived)
  • hide_archived: hide archived records if set to trure
  • subscribed_only: only return subscribed records if set to true (otherwise returns both subscribed & unsubscribed)

The list below highlights the different types of filters:

  • dtfrom (Optional String <yyyyMMdd-HHmmss>) - Example: 20170204-130530
  • dtto (Optional String <yyyyMMdd-HHmmss>) - Example: 20170205-130530
  • filter1 (Optional String <field1>:<op>:<str-value>) - Example: email:eq:bill@gates.com
  • filter2 (Optional String <field2>:<op>:<str-value>) - Example: surname:ct:gates
  • filterN (Optional String <field1>:<op>:<str-value>) - Example: forename:eq:bill
  • fields (Optional String <field1,filed2,fieldN>) - Example: email,forename,surname
  • start (Optional String <start-index>) - Example: start=50
  • count (Optional String <items-to-fetch>) - Example: count=25
  • only_archived (Optional String <only-archived> - Example: only_archived=true
  • hide_archived (Optional String <hide-archived> - Example: hide_archived=true
  • subscribed_only (Optional String <subscribed-only> - Example: subscribed_only=true

NOTE: The <op> field found in the filters can be any one of the following: eq (equals), neq (not-equal), ct (contains), nct (not-contains), stw (starts-with), edw (ends-with).

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • reason - only shown if success is false and indicates the reason of failure.
  • total- represent total number of contacts that meet the search criteria in Kulea
  • count - represent total number of contacts returned (by default set to 100 - use count parameter to override)
  • users - jsonArray representation of each Kulea contact

Example:

{
    "success": true,
    "total": 2,
    "count": 300,
    "users": [
        {
            "id": 4294967667,
            "email": "junaid8@kulea.ma",
            "data": {
                "forename": "junaid8",
                "surname": "bakali8",
                "signupdate": "20170103",
            },
            "archived": false,
            "subscribed": true
        },
        {
            "id": 4294967666,
            "email": "junaid9@kulea.ma",
            "data": {
                "forename": "junaid1",
                "surname": "bakali1",
                "signupdate": "20170104",
            },
            "archived": false,
            "subscribed": true
        }
    ]
}

Definition

Returns a single contact record based on its ID.

REST API URL 

Example URL

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • reason - only shown if success is false and indicates the reason of failure.
  • total- represent total number of contacts within Kulea (same as count)
  • count - represents the total number of contacts within Kulea
  • users - jsonArray representation of Kulea contact

Example:

{
    "success": true,
    "total": 1,
    "count": 1,
    "users": [
        {
            "id": 4294967667,
            "email": "junaid8@kulea.ma",
            "data": {
                "forename": "junaid88",
                "surname": "bakali88",
                "signupdate": "20120103"
            },
            "archived": false,
            "subscribed": true
        }
    ]
}

Definition

Creates a new Kulea Contact record based on Payload. The only real mandatory field for a Contact is an email address, which must be unique for all Kulea Contacts.

REST API URL 

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Body/Payload - JSON

This must be JSON format where fields must correspond to Kulea fields (which you can get from /rest/api/users/fields API).  Also, the field types must be correct otherwise validation may fail. 

{
 "email": "junaid8@kulea.ma",
 "forename":"junaid8",
 "surname":"bakali8",
 "signupdate":"20170201-131200"
 "subscribed":true,
}

NOTE: In the example below the field 'subscribed' will subscribe the user within Kulea.  All new users by default are set to subscribed (without the need to set this field).  If later on you wish to update this record then you may update it by setting 'unsubscribe' to true in the Update Contact API method. 

NOTE: Once a record has been updated with 'unsubscribe' set to true, then you will not be able to set them to 'subscribed' again via the API.

NOTE: You cannot archive a user from using this API method.  For archive please use the DELETE contact API method. 

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • reason - only shown if success is false and indicates the reason of failure.  Examples of failure might be invalid fields, contact already exists (i.e. email address), Json format invalid etc.
  • crm_id - If success then returns the crm_id contact that was created.

Example:

{
    "success": true,
    "crm_id": 4294967668
}

Definition

Updates an existing Kulea Contact record based on ID. You cannot update the email address of an existing contact, but can modify all other fields. The Payload (body) must be in JSON and should only have valid fields.

REST API URL 

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Body/Payload - JSON

This must be JSON format where fields must correspond to Kulea fields (which you can get from /rest/api/users/fields API).  Also, the field types must be correct otherwise validation may fail.  You only need to supply the fields that you want to update in the Payload.  NOTE: You cannot update email for a given Contact.

{
 "forename":"junaid9",
 "surname":"bakali9",
 "unsubscribe":true,
}

NOTE: Here that setting 'unsubscribe' to true will unsubscribe the contact.

NOTE: All new contacts by default are set to subscribed (without the need to set this field).  You can update this status by calling using this API method by setting 'unsubscribe' to true. 

NOTE: Once a record has been updated with 'unsubscribe' set to true, then you will not be able to set them to 'subscribed' again via the API.

NOTE: You cannot archive a contact from using this API method.  For archive please use the DELETE contact API method. 

NOTE: If a contact has been archived the update will not update the record.  No errors will be reported, but the response will highlight that the record is 'archived' (see below).

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • archived - if true then this indicates that the updates were not committed as the record is set to archived (in this instance success might still be true).  If however the record is not archived this field may not be present in the response.
  • reason - only shown if success is false and indicates the reason of failure.  Examples of failure might be invalid fields, Json format invalid, invalid contact id to update etc.
  • crm_id - If success then returns the crm_id that was updated.

Example:

{
    "success": true,
    "crm_id": 4294967668
}

Definition

Archives an existing Kulea Contact record based on ID. It will set the archive status to true for the Contact and as a result will not be visible within Kulea (unless un-archived).

REST API URL 

NOTE: Once a contact is archived their subscribed status is also set to false.  Archived records will not be editable via the REST API.

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • reason - only shown if success is false and indicates the reason of failure.  Examples of failure might be if the id doesn't exist.
  • crm_id - If success then returns the crm_id that was updated.

Example:

{
    "success": true,
    "crm_id": 4294967668
}

Definition

Returns a list of Kulea Events. This list can be filtered against event types and event dates.

REST API URL

Example URL 

Headers

  • Authorization (Mandatory String <API-KEY>) - Example: afeWER£4q3

Query String

The presence of a query string will allow contacts to be filtered accordingly. Some examples are:

  • eventtypes is mandatory and allows filtering against specific event types.  Example eventtype=addedcrm,importedcrm will return all events where the event type is either addedcrm or importedcrm
  • dtfrom and dtto allow you to filter between dates when the events were generated e.g. dtfrom=20170201-133212, will search for all events generated after 01/02/2017 13:32:12.

The list below highlights the different types of filters:

  • eventtypes (Mandatory <eventtype1>,<eventtype2>...) Example: addedcrm,pagevisit
  • dtfrom (Optional String <yyyyMMdd-HHmmss>) - Example: 20170204-130530
  • dtto (Optional String <yyyyMMdd-HHmmss>) - Example: 20170205-130530

NOTE: The eventtypes query string parameter can be anything from the following list of events: pagevisit, genericformcomplete,        emopened, emclickedlink,thirdpartypagevisit, resourcedownload, genericformview, formcomplete,    thirdpartyformcomplete, thirdpartyresourcedownload, buttonclicked, thirdpartybuttonclicked,        thirdpartynewsubscriber, thirdpartynewregistration, newsubscriber, newregistration, formview,        thirdpartyformview, linkclicked, thirdpartylinkclicked, importedcrm, emunsubscribe, addedcrm

Response (application/json)

Response will be a json object with the following fields:

  • success - if true then request was successful; otherwise failed.
  • reason - only shown if success is false and indicates the reason of failure.  Example mandatory eventtypes parameter missing.
  • count - represent total number of events returned
  • events- jsonArray representation of each Kulea event

Example (GET https://<kulea-instance>>/rest/api/users?eventtypes=addedcrm):

{
    "success": true,
    "count": 10,
    "events": [
        {
            "date": "20170629-191335",
            "type": "addedcrm",
            "description": "junaid1@kulea.ma",
            "crm_id": 4294967657
        },
        {
            "date": "20170629-193828",
            "type": "addedcrm",
            "description": "junaid2@kulea.ma",
            "crm_id": 4294967658
        },
        {
            "date": "20170629-193909",
            "type": "addedcrm",
            "description": "junaid3@kulea.ma",
            "crm_id": 4294967659
        },
        {
            "date": "20170629-194004",
            "type": "addedcrm",
            "description": "junaid4@kulea.ma",
            "crm_id": 4294967660
        },
        {
            "date": "20170629-194301",
            "type": "addedcrm",
            "description": "junaid5@kulea.ma",
            "crm_id": 4294967661
        },
        {
            "date": "20170701-001905",
            "type": "addedcrm",
            "description": "junaid6@kulea.ma",
            "crm_id": 4294967662
        },
        {
            "date": "20170701-002001",
            "type": "addedcrm",
            "description": "junaid7@kulea.ma",
            "crm_id": 4294967663
        },
        {
            "date": "20170701-002135",
            "type": "addedcrm",
            "description": "junaid8@kulea.ma",
            "crm_id": 4294967664
        },
        {
            "date": "20170725-141901",
            "type": "addedcrm",
            "description": "junaid8@kulea.ma",
            "crm_id": 4294967667
        },
        {
            "date": "20170726-143431",
            "type": "addedcrm",
            "description": "junaid9@kulea.ma",
            "crm_id": 4294967668
        }
    ]
}