Mobile apps notification API v 1.0

This is a simple API allowing connecting Incomaker to mobile applications.

The API consists of two components:

  • Commons API for the synchronization of app data (contacts, segments...) with Incomaker
  • A user can set hooks that will be called by Incomaker if a notification should be posted to an application

Hooks 1.0

Hooks are events in Incomaker where a custom call to an external application could be placed. If you e.g. hang on a hook at blog post, after a post is sent to a blog, Incomaker calls the URL of the external method with the respective parameters.

In the current version, hooks are not user-configurable. Please, send a request with your URL to the support.

The hook could be GET or POST method. An example of the POST call is JSON as follows:

"data":"

{\"keywords\":

{\"Newsletter\":[\"Segment A\",\"Segment B",\"Segnebt C\",\"Segment D"]},

\"id\":\"19222\",

\"title\":\"Wonderful blogpost title\",

\"url\":\"http:\/\/www.example.com\/best-article-on-our-web.html\"

}"

Segments must fit with the ones defined in Incomaker (see the next chapter to find out, how to retrieve them).

id is a post ID in a CMS.

Title is a title of the article in the CMS.

URL is a URL of the article in the CMS.

Incomaker Commons API

Current version of API is 1.0 that will be supported at least until the end of 12/2019. We are working on Incomaker Commons API 2.0. that should be available in 2018.

Endpoints

Live endpoint:

https://api.incomaker.com/incomaker-ws/ws/UpstreamAPI

Development endpoint (please, contact support for access):

https://devb.incomaker.com/incomaker-ws/ws/UpstreamAPI

Methods

getAllSegments

getClientByEmail

getClient

createClient

editClient

Function Get segments from the account
URL
/getAllSegments
Method POST
Parameters
apiKey UUID API key assigned to the user's account/plugin.
sessionId CHAR(32)

Client generates sessionId. Use the same sessionId for all further calls to keep track of the whole process.

BINARY(16) encoded as a string of hex values.

Success result
200 OK
{"state":"success","segmentStructure":
"[{\"name\":\"Product\",\"groups\":
[{\"ordering\":20,\"name\":\"Group A\",\"id\":204,
\"tags\":[{\"ordering\":30,\"name\":
\"Product A\",\"id\":16823},{\"ordering\":20,\"name\":
\"Product B\",\"id\":16824}]},
{\"ordering\":10,\"name\":\"Group B\",\"id\":205,
\"tags\":[]}],\"id\":755,
\"tags\":[{\"ordering\":10,\"name\":
\"Product C\",\"id\":16825}]}]"}
Failure result
400 Bad Request
{"state":"fail","errorMsg":"ERR_PLUGIN_PENDING"}
call example:
curl --insecure -d apiKey="752259a5-4d69-464c-839f-a80bb90be821" -d sessionId="154b32b8a1fb4fdc89d56e2de3d3663d" https://api.incomaker.com/incomaker-ws/ws/UpstreamAPI/getAllSegments
Remark tags mean segments or subscriptions.

Function Create new contact and assign it to segments.
URL
/createClient
Method POST
Parameters
apiKey UUID API key assigned to the user's account/plugin.
sessionId CHAR(32)

Client generates sessionId. Use the same sessionId for all further calls to keep track of the whole process.

BINARY(16) encoded as a string of hex values.

clientDetail VARCHAR

Escaped JSON with email address of the new contact.

{\"email\":\"zkouskaSubscribe2[at]example[dot]com\"}
clientSegmentIds VARCHAR

List of segments to assign to the respective contact

[16823, 16824]
Success result
200 OK
{"clientId":"e5d17cf0-cbda-11e7-8bc9-8d675e2d7969","state":"success"}
Failure result
400 Bad Request
{"state":"fail","errorMsg":"ERR_PLUGIN_PENDING"}
call example:
curl --insecure -d apiKey="752259a5-4d69-464c-839f-a80bb90be821" -d sessionId="154b32b8a1fb4fdc89d56e2de3d3663d" --data-urlencode clientDetail="{\"email\":\"zkouskaSubscribe2[at]example[dot]com\"}"  --data-urlencode clientSegmentIds="[16823, 16824]" https://api.incomaker.com/incomaker-ws/ws/UpstreamAPI/createClient
Remark
 

Function Return a contact with the respective email.
URL
/getClientByEmail
Method POST
Parameters
apiKey UUID API key assigned to the user's account/plugin.
sessionId CHAR(32)

Client generates sessionId. Use the same sessionId for all further calls to keep track of the whole process.

BINARY(16) encoded as a string of hex values.

email VARCHAR

String with contact's email.

zkouskaSubscribe2[at]example[dot]com
Success result
200 OK
{"client":"{\"clientId\":\"e5d17cf0-cbda-11e7-8bc9-8d675e2d7969\",
\"email\":\"zkouskaSubscribe2[at]example[dot]com\",
\"clientSegmentsSubscribed\":[16823,16824]}","state":"success"}
Failure result
400 Bad Request
{"state":"fail","errorMsg":"ERR_PLUGIN_PENDING"}
call example:
curl --insecure -d apiKey="752259a5-4d69-464c-839f-a80bb90be821" -d sessionId="154b32b8a1fb4fdc89d56e2de3d3663d" -d email="zkouskaSubscribe2[at]example[dot]com" https://api.incomaker.com/incomaker-ws/ws/UpstreamAPI/getClientByEmail
Remark
 

Function Return a contact with the respective ID.
URL
/getClient
Method POST
Parameters
apiKey UUID API key assigned to the user's account/plugin.
sessionId CHAR(32)

Client generates sessionId. Use the same sessionId for all further calls to keep track of the whole process.

BINARY(16) encoded as a string of hex values.

clientId UUID

Contact ID.

e5d17cf0-cbda-11e7-8bc9-8d675e2d7969
Success result
200 OK
{"client":"{\"clientId\":\"e5d17cf0-cbda-11e7-8bc9-8d675e2d7969\",
\"email\":\"zkouskaSubscribe2[at]example[dot]com\",
\"clientSegmentsSubscribed\":[16823,16824]}","state":"success"}
Failure result
400 Bad Request
{"state":"fail","errorMsg":"ERR_PLUGIN_PENDING"}
call example:
curl --insecure -d apiKey="752259a5-4d69-464c-839f-a80bb90be821" -d sessionId="154b32b8a1fb4fdc89d56e2de3d3663d" -d clientId="e5d17cf0-cbda-11e7-8bc9-8d675e2d7969" https://api.incomaker.com/incomaker-ws/ws/UpstreamAPI/getClient
Remark
 

Function Update a contact
URL
/editClient
Method POST
Parameters
apiKey UUID API key assigned to the user's account/plugin.
sessionId CHAR(32)

Client generates sessionId. Use the same sessionId for all further calls to keep track of the whole process.

BINARY(16) encoded as a string of hex values.

clientDetail VARCHAR

Escaped JSON with email address of the new contact and contact Id. Contact Id has to be a valid ID of an existing contact. Email could be subject to change.

{\"email\":\"test2[at]example[dot]com\", \"contactId\":\"e5d17cf0-cbda-11e7-8bc9-8d675e2d7969\"}
clientSegmentIds VARCHAR

List of segments to assign to the respective contact. If you need to unsubscribe the contact completely, use an empty array. To preserve the current state of subscriptions, you need to get a list of the current subscriptions and return it adjusted. 

[16824]
Success result
200 OK
{"clientId":"e5d17cf0-cbda-11e7-8bc9-8d675e2d7969","state":"success"}
Failure result
400 Bad Request
{"state":"fail","errorMsg":"ERR_PLUGIN_PENDING"}
call example:
curl --insecure -d apiKey="752259a5-4d69-464c-839f-a80bb90be821" -d sessionId="154b32b8a1fb4fdc89d56e2de3d3663d" --data-urlencode clientDetail="{\"email\":\"test2[at]example[dot]com\", \"contactId\":\"e5d17cf0-cbda-11e7-8bc9-8d675e2d7969\"}"  --data-urlencode clientSegmentIds="[16824]" https://api.incomaker.com/incomaker-ws/ws/UpstreamAPI/editClient
Remark Apparently, ClientId cannot be changed.