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
}
]
}