Rest API

Introduction

REST stands for Representational State Transfer and is a style of software architecture that relies on stateless, client-server and cacheable communication protocols. HTTP is most commonly used and is the protocol that will be used for the REST API.

HTTP requests are used to post data (update and insert), retrieve data or search.

Incoming requests are by default queued (asynchronous request) until processing and process responses are returned to the same queue. Direct requests (synchronous) interrogate the database directly and are permitted less often. The document indicates clearly when this is the case. Some requests can even use streaming where results are already returned while the request is still processing.

When a request comes in a series of checks are made in the following order:

  • Quota check
  • Authentication verification
  • IP filter check

The major benefits of REST technology are

  • Scalability
  • High volume
  • Both Synchronous and asynchronous processing
  • Language independent

Example of the structure a REST request:
http://[server]/phonebook/UserDetails/12345

This is an example of what a request might look like when retrieving the details of a specific user from a phonebook.

Example of an http path for direct request:
https://[server]/restapi/api/sync/..

Example of a path for queued request:
https://[server]/restapi/api/async/..

 

Dedicated API user

To be able to use the REST API a dedicated API user has to be created.

A name and login needs to be entered for the API user. The user's password is generated automatically and is used for hashing. The refresh button to the right of the field allows regenerating the password.


The API user must assign specific rights, indicating what operations can be performed through the API by that user and what operations can't.

 

API Functionality

Quota management

Quota management checks the number of incoming requests and blocks them when the quota for the respective client has been reached. At every new request that arrives the quota counter is decreased and returned. There are 3 possible quota settings, one for each type of request:

  • Synchronous requests: This is a direct request and the result is returned immediately. The quota set for this type of request is stricter as it requires an immediate access to the database. This also means that for GET requests the cache is never consulted.
  • Asynchronous requests:
    • PUT/POST: Requests are queued and processed in the background. Status code 200/OK is returned immediately.
    • GET:  The cache is consulted first for a cached result, if unsuccessful the database will be queried.
    • Stream requests: With this type of request answers are returned continuously while the request is being handled. There is no buffering of the response on the server.

For each request made, the remaining requests will be returned in the HTTP HEADER of the response.

  • X-Quota-Sync
  • X-Quota-Async
  • X-Quota-Stream

Requests that fail the quota management check and that are not authenticated are not taken into account when calculating the quota. An HTTP error 403 is returned when the request is not within range.

Note: The quota is generally lower for direct(synchronous) requests as the database itself is interrogated. The default timespan of a quota is 5 minutes. After 5 minutes the quota counter is reset.

By default, all requests are configured with the following quota limits:

  • Sync: 25 requests
  • Async: 100 requests
  • Stream: 1 request
  • LifespanInSeconds: 300

Note: If needed, quota adjustments can be reviewed upon request by creating a ticket on our support portal.

Authentication

Every request must be authenticated. The authentication is based on the user name (readable), a hash code and a timestamp, all passed on through the Authorization HTTP header. The combination is preceded by 'hmac'

Example:
Authorization: hmac rdtest1:2AC5E7249082E2A76F6A0AD30DA37964D7522C8E1BBFD084705D52791D83EAA7:1372667542

Following is an example of a direct GET request where 2 fields (id, name) are retrieved from a profile with ID=1 in a userlist with ID=1:

1372667542-GET-/restapi/api/sync/lists/1/profiles/1?fields=id,name

  • The time stamp is a UNIX timestamp. This MUST be the same timestamp used to generate the hash code.
  • The key used to encode can be found in the API user properties in the Manager. (Check out section Dedicated API user)

When a request is received at the server, the user name in the request is used to retrieve information from the Marketing system. With this information the request parameters are rehashed using the client's password and compared with the hash in the authentication HTTP header. If this is the same, authentication succeeded.

The Timestamp is added both to the header and to the signature. Both are compared and must be equal for the request to be accepted. Additionally, a check is made to verify if the timestamp is within a specified interval of 5 minutes compared to the current server time.

Note: UTC times are used.

Technical note:
An HMAC can be used to determine whether a message sent over an insecure channel has been tampered with, provided that the sender and receiver share a secret key. The sender computes the hash value for the original data and sends both the original data and hash value as a single message. The receiver recalculates the hash value on the received message and checks that the computed HMAC matches the transmitted HMAC.
Any change to the data or the hash value results in a mismatch, because knowledge of the secret key is required to change the message and reproduce the correct hash value. Therefore, if the original and computed hash values match, the message is authenticated.
HMACSHA256 accepts keys of any size, and produces a hash sequence 256 bits in length.

 

IP filters

To filter requests and allow IP's to perform requests, the web.config file is edited. Only configured IPs are granted access.

A dedicated section <api> allows configuring these IP filters.

Copy

Example:

<api>
    <ipFilters>
        <ip address="162.3.8.1" />
    </ipFilters>
</api>

Some explanations:

  • All IP filters are included in the <ipFilters> tag.
  • The <ip> tag allows defining filters for a single IP, or a subnet using either the CIDR notation or providing a value for ‘mask’.
  • The value for ‘address’ must be unique.

 

Paging

When requests return many results, it is handy to be able to perform paging on these results.

Note: Paging is not available for all requests but if it is it is by default active.

The mechanism works as follows:

When a result is returned, it contains the records of the current page and an indication of the total number of 'records' returned by the request. As the records are paged, the result contains links (url) indicating where the previous x records or next x records can be retrieved.

Copy

Example:

{
    "result": [...],
    "total": 999,
    "_links": [{
        "rel": "next"
        "uri": "action-url?offset=401&size=200",
        "verb": "GET"
    } {
        "rel": "prev",
        "uri": "action-url?offset=201&size=200",
        "verb": "GET"
    }]
}
  • "result" contains the actual result.
  • "_links" contains the path to the next or previous x records in the result.
  • Offset indicates the start of the range. Size indicates the number of results in the page. The default is 200 and the maximum is 500.

The indicated URI must be added to the request URL after the “?”

Example:
1372667542-GET-/restapi/api/async/lists?offset=201&size=200

 

Functions

The key abstraction of information in REST is called a resource. Currently following resources are at hand:

  • Profile: Represents a record from a user list, including 1:1 profile extensions.
  • Lists: represents a user list
  • Campaign: Represents a Marketing flow.

The operation to be executed is included in the HTTP header and can be one of the following:

  • GET: Retrieve information
  • PUT: Update a resource
  • POST: Create new resource

Below you'll find an overview of the resources and methods allowed, with for each one an indication of the path to use, if direct requesting is supported, if streaming is allowed, if paging is possible. The default quota limits is provided as well.

Direct requests return a response. The url of direct requests contain the 'sync' element.

Some understanding on queued requests:

  • The url of queued requests contain the 'async' element.
  • Queued requests return a HTTP 200 (indicating the request has been accepted) and OK

Example:
Perform the following async request:
HTTP GET http://someserver.com/restapi/api/async/lists/1/profiles/91376
It will return the following response:
HTTP 200

 

Campaigns

Trigger (with campaign ID)

DESCRIPTION

Use this method to enter data in an action list and trigger a campaign that sends an instant email with data from the action list. Note that the campaign must be designed to work with action lists and that a gate needs to be created as well.

Key

Campaigns-Trigger

Path

restapi/api/async/campaigns/{id}/trigger

Method

POST

Paging support

No

Stream support

No

Direct request support

No

Quota

Sync

Async

Stream

Life in seconds

0

100

0

300

The following data needs to be passed on with the request:

  • ActionList: contains the ID of the action list
  • ActionListRecord: contains the data that needs to be put in the record
  • Gate: The name of the gate used to access the campaign
  • GateInput (optional): input parameters passed on to the gate
  • User: The ID of the user for who the campaign is triggered
  • UserListId: the ID of the user list to which the user belongs.
Copy
Example of a request:
HTTP POST http://someserver.com/restap/api/async/campaigns/1378/trigger
{
    "ActionList": 862,
    "ActionListRecord": {
        "ACTIONCODE": "TESTDATA",
        "CONTENT": "[{\"ID\": 1,\"PARAM\":\"DATA\",\"CONTENT\":{\"CAPTION\":\"REST Api Test 3/07/2013 8:45:38\"}}]"
    },
    "Gate": "TRIGGERGATE",
    "GateInput": null,
    "User": 1,
    "UserListId": 863
}
The response:
HTTP 200 OK

 

Trigger (without campaign ID)

DESCRIPTION

Use this method to enter data in an action list and trigger a campaign that sends an instant email with data from the action list. Note that the campaign must be designed to work with action lists and that a gate needs to be created as well.

Key

Campaigns-Trigger

Path

restapi/api/async/campaigns/trigger

Method

POST

Paging support

No

Stream support

No

Direct request support

No

Quota

Sync

Async

Stream

Life in seconds

0

100

0

300

This trigger works the same as the one with a campaign ID (7.1.1). The only difference is that a gate is passed in the payload which refers to a campaign, so this implicitly identifies the campaign, and thus requires no campaign id.

The following data needs to be passed on with the request:

  • ActionList: contains the ID of the action list
  • ActionListRecord: contains the data that needs to be put in the record
  • Gate: The name of the gate used to access the campaign
  • GateInput (optional): input parameters passed on to the gate
  • User: The ID of the user for who the campaign is triggered
  • UserListId: the ID of the user list to which the user belongs.
Copy
Example of a request:
HTTP POST http://someserver.com/restap/api/async/campaigns/trigger
{
    "ActionList": 862,
    "ActionListRecord": {
        "ACTIONCODE": "TESTDATA",
        "CONTENT": "[{\"ID\": 1,\"PARAM\":\"DATA\",\"CONTENT\":{\"CAPTION\":\"REST Api Test 3/07/2013 8:45:38\"}}]"
    },
    "Gate": "TRIGGERGATE",
    "GateInput": null,
    "User": 1,
    "UserListId": 863
}
The response:
HTTP 200 OK

 

TriggerbyJson

DESCRIPTION

Use this method to trigger by Gate and optionally send parameters

Key

CampaignAPITriggerByJson

Path

restapi/api/sync/campaigns/triggerbyjson

restapi/api/async/campaigns/triggerbyjson

Method

POST

Paging support

No

Stream support

No

Direct request support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a request:
POST api/async/campaigns/triggerbyjson

Post body:
{
    "Gate": "DBLX_GATE",
    "GateInput": {
        "PARAM1": "FIRST",
        "PARAM2": "SECOND"
    }
}
The response:
HTTP 200 True

 

TriggerbyJsonWithResult

DESCRIPTION

Use this method to trigger by Gate and optionally send parameters

Key

CampaignAPITriggerByJsonWithResult

Path

restapi/api/sync/campaigns/triggerbyjsonwithresult

restapi/api/async/campaigns/triggerbyjsonwithresult

Method

POST

Paging support

No

Stream support

No

Direct request support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a request:
POST api/async/campaigns/triggerbyjsonWithResult

Post body:
{
    "Gate": "DBLX_GATE",
    "GateInput": {
        "PARAM1": "FIRST",
        "PARAM2": "SECOND"
    }
}
The response:
// In case of success:
HTTP status 200
// and a JSON object like this:
{
    "IsSuccess": true,
    "Error": ""
}

// In case of failure:
HTTP status 400
// and a JSON object containing an error:
{
    "IsSuccess": false,
    "Error": "<some error string>"
}

 

Action Lists

Create One

DESCRIPTION

Use this method to create data for one specific action list by providing the desired input. ListId, UserId and ActionCode are mandatory. CampaignId, ActionId and State are not allowed. Any other posted fields are arbitrary but are checked for existence against the action list table.

Key

ActionList-Post

Path

restapi/api/sync/lists/{id}/actions

restapi/api/async/lists/{id}/actions

Method

POST

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/sync/lists/210/actions
{
  "ActionId": "4",
  "ListId": "171",
  "UserId": "1",
  "ActionCode": "unit test"
}
The result returned by the request looks like following:
HTTP 200 OK

{
    "ActionId": "4",
    "ListId": "171",
    "UserId": "1",
    "ActionCode": "unit test",
    "CREATED_DT": "2013-08-21T09:02:03.0591404+02:00",
    "Id": 10745041
}

Two extra fields, CREATED_DT and the assigned record ID, are added.

 

Create Many (streamed)

DESCRIPTION

Use this method to create data for one or many action list entries by providing the desired input. ListId, UserId and ActionCode are mandatory. CampaignId, ActionId and State are not allowed. Any other posted fields are arbitrary but are checked for existence against the action list table.

For this call it is required to provide the fields which will be posted on the first line, pipe-separated.

Key

ActionList-Post-Stream

Path

restapi/api/stream/lists/{id}/actions/post?mode={create/append}

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/stream/lists/210/actions/post?mode=append

ListId | UserId | ActionCode

{"ListId": "171", "UserId": "1", "ActionCode": "streaming unit test"}
{"ListId": "171", "UserId": "2", "ActionCode": "streaming unit test"}
{"ListId": "171", "UserId": "3", "ActionCode": "streaming unit test"}
The result returned by the request looks like following:
HTTP 200 OK

No additional content is returned.

 

Create action list

DESCRIPTION

Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property.

Key

Lists-Post

Path

restapi/api/sync/lists

restapi/api/async/lists

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists

Post body:
{
    "name": "ACTION_EXAMPLE_LIST",
    "type": "ACTIONLIST",
    "folder": 1964,
    "owner": 279,
    "disabled": 0,
    "fields": [{
        "column": "title",
        "dataType": "text",
        "maxLength": 50,
        "required": true
    }, {
        "column": "description",
        "dataType": "long text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "act_int",
        "dataType": "numeric",
        "required": true
    }, {
        "column": "act_long",
        "dataType": "long",
        "required": false
    }, {
        "column": "act_float",
        "dataType": "float",
        "required": true
    }, {
        "column": "act_datetime",
        "dataType": "datetime",
        "required": true
    }, {
        "column": "act_date",
        "dataType": "date",
        "required": true
    }, {
        "column": "act_boolean",
        "dataType": "boolean",
        "required": false
    }]
}
Copy
The result returned by the request looks like following:
HTTP 200 OK

{
    "id": 4248,
    "type": "ACTIONLIST",
    "tablename": "DB_DEVU_DATA.dbo.ACTION_ACTION_EXAMPLE_LIST",
    "name": "ACTION_EXAMPLE_LIST",
    "description": null,
    "folder": 1964,
    "owner": 279,
    "disabled": null,
    "fields": [{
            "column": "ID",
            "primary_key": true,
            "required": true,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "CREATED_DT",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Datetime"
        }, {
            "column": "MODIFIED_DT",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Datetime"
        }, {
            "column": "EXEC_DT",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Datetime"
        }, {
            "column": "CAMPAIGNID",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "ACTIONID",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "LISTID",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "USERID",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "STATE",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "ACTIONCODE",
            "primary_key": false,
            "required": false,
            "maxlength": 50,
            "optionlist": 0,
            "datatype": "Text"
        }, {
            "column": "title",
            "primary_key": false,
            "required": true,
            "maxlength": 50,
            "optionlist": 0,
            "datatype": "Text"
        },
        {
            "column": "description",
            "primary_key": false,
            "required": false,
            "maxlength": 50,
            "optionlist": 0,
            "datatype": "Long Text"
        }, {
            "column": "act_int",
            "primary_key": false,
            "required": true,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        }, {
            "column": "act_long",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Long"
        }, {
            "column": "act_float",
            "primary_key": false,
            "required": true,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Float"
        }, {
            "column": "act_datetime",
            "primary_key": false,
            "required": true,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Datetime"
        }, {
            "column": "act_date",
            "primary_key": false,
            "required": true,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Date"
        }, {
            "column": "act_boolean",
            "primary_key": false,
            "required": false,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Boolean"
        }
    ],
    "_links": [{
        "rel": "self",
        "uri": "api/async/lists/4248",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "api/async/lists/4248",
        "verb": "PUT"
    }]
}

 

Lists

Create One

DESCRIPTION

Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property. All listed fields in the example are mandatory.

Key

Lists-Post

Path

restapi/api/sync/lists

restapi/api/async/lists

Method

POST

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/sync/lists

{
    "type": "USERLIST",
    "tablename": "USERS_DEMO_MATRIX",
    "name": "DEMO_MATRIX - MASTER LIST",
    "folder": "1",
    "owner": "9",
    "disabled": "0",
    "fields": [{
        "column": "street",
        "dataType": "text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "areacode",
        "dataType": "numeric",
        "required": false,
        "optionlist": 23
    }]
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "id": "1",
    "type": "USERLIST",
    "tablename": "USERS_DEMO_MATRIX",
    "name": "DEMO_MATRIX - MASTER LIST",
    "folder": "1",
    "owner": "9",
    "disabled": "0",
    "fields": [{
        "column": "street",
        "dataType": "text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "areacode",
        "dataType": "numeric",
        "required": false,
        "optionlist": 23
    }],
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "PUT"
    }, {
        "rel": "schema",
        "uri": "restapi/api/sync/lists/1/schema",
        "verb": "GET"
    }, {
        "rel": "relations",
        "uri": "restapi/api/sync/lists/1/relations",
        "verb": "GET"
    }, {
        "rel": "search",
        "uri": "restapi/api/sync/lists/1/profiles/search",
        "verb": "POST"
    }, {
        "rel": "profiles",
        "uri": "restapi/api/sync/lists/1/profiles",
        "verb": "GET"
    }]
}


The result returns

  • The list ID
  • Type
  • Tablename
  • Name
  • Folder
  • Owner
  • Disabled
  • The _links section provides insight in all other actions that can be performed on the list.

 

Read One

DESCRIPTION

Use this method to retrieve the metadata for one specific list by using the ID of the list.

Key

ActionList-Get

Path

restapi/api/sync/lists/{id}/actions

restapi/api/async/lists/{id}/actions

Method

GET

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the URL path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP GET http://someserver.com/restapi/api/sync/lists/1
Copy
The result looks like the following:
HTTP 200 OK

{
    "id": "1",
    "type": "USERLIST",
    "tablename": "USERS_DEMO_MATRIX",
    "name": "DEMO_MATRIX - MASTER LIST",
    "folder": "1",
    "owner": "9",
    "disabled": "0",
    "fields": [{
        "column": "street",
        "dataType": "text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "areacode",
        "dataType": "numeric",
        "required": false,
        "optionlist": 23
    }],
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "PUT"
    }, {
        "rel": "schema",
        "uri": "restapi/api/stream/lists/1/schema",
        "verb": "GET"
    }, {
        "rel": "relations",
        "uri": "restapi/api/stream/lists/1/relations",
        "verb": "GET"
    }, {
        "rel": "search",
        "uri": "restapi/api/stream/lists/1/profiles/search",
        "verb": "POST"
    }, {
        "rel": "profiles",
        "uri": "restapi/api/stream/lists/1/profiles",
        "verb": "GET"
    }]
}

The result returns

  • The list ID
  • Type
  • Tablename
  • Name
  • Folder
  • Owner
  • Disabled
  • The _links section provides insight in all other actions that can be performed on the list.

 

Read All (paged)

DESCRIPTION

Use this method to retrieve the metadata for all lists the user has access to

Key

ActionList-Get

Path

/restapi/api/sync/lists

/restapi/api/async/lists

Method

GET

Paging support

Yes

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a synchronous request:
HTTP GET http://someserver.com/restapi/api/sync/lists
Copy
The result of the request is as follows (note that only one list record is displayed in the range of 200 records of a total of 635 lists):
HTTP 200 OK

{
    "result": [{
        "id": "1",
        "type": "USERLIST",
        "tablename": "USERS_DEMO_MATRIX",
        "name": "DEMO_MATRIX - MASTER LIST",
        "folder": "1",
        "owner": "9",
        "disabled": "0",
        "_links": [{
            "rel": "self",
            "uri": "restapi/api/sync/lists/1",
            "verb": "GET"
        }, {
            "rel": "self",
            "uri": "restapi/api/sync/lists/1",
            "verb": "PUT"
        }, {
            "rel": "schema",
            "uri": "restapi/api/sync/lists/1/schema",
            "verb": "GET"
        }, {
            "rel": "relations",
            "uri": "restapi/api/sync/lists/1/relations",
            "verb": "GET"
        }, {
            "rel": "search",
            "uri": "restapi/api/sync/lists/1/profiles/search",
            "verb": "POST"
        }, {
            "rel": "profiles",
            "uri": "restapi/api/sync/lists/1/profiles",
            "verb": "GET"
        }]
    }, ...],
    "total": 635,
    "_links": [{
        "rel": "next",
        "uri": "restapi/api/sync/lists/?offset=201&size=200",
        "verb": "GET"
    }]
}

For each list information is returned on

  • The list ID
  • Type
  • Tablename
  • Name
  • Folder
  • Owner
  • Disabled
  • The _links section provides an overview of all other actions that can be performed on the resource. The uri to be able to perform the action is provided as well.

 

Read All (streamed)

DESCRIPTION

Use this method to retrieve the metadata for all lists the user has access to and this using the stream method.

Key

Lists-Get-Stream

Path

/restapi/api/stream/lists

Method

GET

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
HTTP GET http://someserver.com/restapi/api/stream/lists
Copy
The result looks like the following (note that each result returned is separated by a line break):
HTTP 200 OK

First result:
{
    "id": "1",
    "type": "USERLIST",
    "tablename": "USERS_DEMO_MATRIX",
    "name": "DEMO_MATRIX - MASTER LIST",
    "folder": "1",
    "owner": "9",
    "disabled": "0",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "PUT"
    }, {
        "rel": "schema",
        "uri": "restapi/api/stream/lists/1/schema",
        "verb": "GET"
    }, {
        "rel": "relations",
        "uri": "restapi/api/stream/lists/1/relations",
        "verb": "GET"
    }, {
        "rel": "search",
        "uri": "restapi/api/stream/lists/1/profiles/search",
        "verb": "POST"
    }, {
        "rel": "profiles",
        "uri": "restapi/api/stream/lists/1/profiles",
        "verb": "GET"
    }]
}

Second result:
{
    "id": "3",
    "type": "ACTIONLIST",
    "tablename": "ACTION_EXT_ACTIONS",
    "name": "EXT_ACTIONS",
    "folder": "5",
    "owner": "18",
    "disabled": "null",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/3",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/3",
        "verb": "PUT"
    }, {
        "rel": "schema",
        "uri": "restapi/api/stream/lists/3/schema",
        "verb": "GET"
    }, {
        "rel": "relations",
        "uri": "restapi/api/stream/lists/3/relations",
        "verb": "GET"
    }, {
        "rel": "search",
        "uri": "restapi/api/stream/lists/3/profiles/search",
        "verb": "POST"
    }, {
        "rel": "profiles",
        "uri": "restapi/api/stream/lists/3/profiles",
        "verb": "GET"
    }]
}

For each list information is returned on

  • The list ID
  • Type
  • Tablename
  • Name
  • Folder
  • Owner
  • Disabled
  • The _links section provides an overview of all other actions that can be performed on the resource. The uri to be able to perform the action is provided as well.

 

Modify One

DESCRIPTION

Use this method to modify the metadata for one specific list by using the ID of the list and the desired data to modify. Fields with no change must be supplied with value ‘null’. 'type' is mandatory.

Key

Lists-Put

Path

/restapi/api/sync/lists/{id}

/restapi/api/async/lists/{id}

Method

PUT

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of direct request:
HTTP PUT http://someserver.com/restapi/api/sync/lists/1

{
    "id": "1",
    "type": null,
    "tablename": null,
    "name": "Table Caption Changed",
    "folder": null,
    "owner": null,
    "disabled": null
}
Copy
The result looks like the following:
HTTP 200 OK

{
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1",
        "verb": "PUT"
    }, {
        "rel": "schema",
        "uri": "restapi/api/sync/lists/1/schema",
        "verb": "GET"
    }, {
        "rel": "relations",
        "uri": "restapi/api/sync/lists/1/relations",
        "verb": "GET"
    }, {
        "rel": "search",
        "uri": "restapi/api/sync/lists/1/profiles/search",
        "verb": "POST"
    }, {
        "rel": "profiles",
        "uri": "restapi/api/sync/lists/1/profiles",
        "verb": "GET"
    }]
}

The result returns

  • The list ID
  • Type
  • Tablename
  • Name
  • Folder
  • Owner
  • Disabled
  • The _links section provides insight in all other actions that can be performed on the list.

 

Get searchable fields

DESCRIPTION

Use this method to retrieve a list of fields that are indexed for search purposes.

Key

Lists-Get-SearchFields

Path

/restapi/api/sync/lists/{id}/searchfields

Method

GET

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of direct request:
HTTP GET http://someserver.com/restapi/api/sync/lists/1845/searchfields
Copy
The result returned by the request looks like the following:
HTTP 200 OK

[{
    "column": "ID",
    "primary_key": true,
    "required": true,
    "maxlength": -1,
    "optionlist": 0,
    "datatype": "Numeric",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1845/fields/id",
        "verb": "PUT"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1845/fields/id",
        "verb": "DELETE"
    }]
}, {
    "column": "NAME",
    "primary_key": false,
    "required": false,
    "maxlength": 50,
    "optionlist": 0,
    "datatype": "Text",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1845/fields/name",
        "verb": "PUT"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1845/fields/name",
        "verb": "DELETE"
    }]
}]

 

Lists Profiles

Create One

DESCRIPTION

Use this method to create a new user record in a specific user list. It is possible to insert data in 1:1 profile extensions as well.

Key

Profiles-Post

Path

/restapi/api/sync/lists/{id}/profiles

/restapi/api/async/lists/{id}/profiles

Method

POST

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/sync/lists/863/profiles

    {
        "Name": "Test user",
        "Mail": "testuser-restapi@selligent.be",
        "MyField": "test dynamic field",
        "ActionTriggerlink.Created_dt": "2013-07-03T10:09:01.4440802+02:00",
        "ActionTriggerlink.CampaignId": 1376,
        "ActionTriggerlink.ActionId": 2,
        "ActionTriggerlink.ListId": 863,
        "ActionTriggerlink.UserId": 1,
        "ActionTriggerlink.State": 30,
        "ActionTriggerlink.ActionCode": "RestApiTest-3/07/2013 10:09:01",
        "Extensions.TwitterHandle": "suddenelfilio",
        "Domains.MailDomain": "selligent.be"
    }

In the above example 'ActionTriggerLink', 'Extensions' and 'Domains' are profile extensions of the userlist with id=863.

Note that the fields passed on to the request differ from one userlist to another and should be adapted accordingly.

Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "Name": "Test user",
    "Mail": "testuser-restapi@selligent.be",
    "MyField": "test dynamic field",
    "ActionTriggerlink.Created_dt": "2013-07-03T10:09:02.7921573+02:00",
    "ActionTriggerlink.CampaignId": 1376,
    "ActionTriggerlink.ActionId": 2,
    "ActionTriggerlink.ListId": 863,
    "ActionTriggerlink.UserId": 119,
    "ActionTriggerlink.State": 30,
    "ActionTriggerlink.ActionCode": "RestApiTest-3/07/2013 10:09:01",
    "ActionTriggerlink.Id": 145,
    "Extensions.TwitterHandle": "suddenelfilio",
    "Extensions.Id": 72,
    "Domains.MailDomain": "selligent.be",
    "Domains.MAIL": "testuser-restapi@selligent.be",
    "Domains.Id": 64,
    "CREATED_DT": "2013-07-03T10:09:02.7701561+02:00",
    "EXTENSIONID": 72,
    "Id": 119
}

 

Create Many (streamed)

DESCRIPTION

Use this method to create data for one or more user record(s) in a specific user list. It is not possible to insert any profile extensions.

For this call it is required to provide the fields which will be posted on the first line, pipe-separated.

Key

Profiles-Post-Stream

Path

/restapi/api/stream/lists/{id}/profiles/post?mode={create/append}

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/stream/lists/210/actions/post?mode=append

Name | Mail
{"Name": "John Doe 1", "Mail": "John1@test.com"}
{"Name": "John Doe 2", "Mail": "John2@test.com"}
{"Name": "John Doe 3", "Mail": "John3@test.com"}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

No additional content is returned.

 

Read One

DESCRIPTION

Use this method to retrieve information on a specific user record in a specific user list. The scope can be limited by specifying the fields in the url of the request.

Key

Profiles-Get-Id

Path

/restapi/api/sync/lists/{id}/profiles/{pid}{?fields=x,y,z}

/restapi/api/async/lists/{id}/profiles/{pid}{?fields=x,y,z}

Method

GET

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP GET http://someserver.com/restapi/api/sync/lists/411/profiles/14?fields=id,mail,social_linkedin.firstname,social_linkedin.lastname 

In the above example a user record with id=14 is retrieved from the userlist with id=411. The fields returned are limited to the 'id', 'mail' and 'firstname' and 'lastname' in the profile extension 'social_linkedin'

Copy
The result looks like the following:
{
    "ID": 14,
    "MAIL": "filip@wolkjes.net",
    "SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
    "SOCIAL_LINKEDIN.LASTNAME": "LeRoi",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/411/profiles/14?fields=id,mail,social_linkedin.firstname,social_linkedin.lastname",
        "verb": "GET"
    }, {
        "rel": "list",
        "uri": "restapi/api/sync/lists/411",
        "verb": "GET"
    }]
}

The _links section provides an overview of all other actions that can be performed on the resource.

 

Read All (paged)

DESCRIPTION

Use this method to retrieve all user records from a specific user list. The scope can be limited by specifying the fields in the url.

When including fields from 1:1 relations, which in reality contain 1:n data, multiple records of the same profile are returned.

Key

Profiles-Get

Path

/restapi/api/sync/lists/{id}/profiles{?fields=x,y,z}

/restapi/api/async/lists/{id}/profiles{?fields=x,y,z}

Method

GET

Paging support

Yes

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP GET http://someserver.com/restapi/api/sync/lists/1/profiles
Copy
The result looks like the following:
{
    "result": [{
        "ID": 340967,
        "MAIL": "jane.doe0@gmail.com",
        "NAME": "Doe0",
        "OPTOUT": 0,
        "TESTUSER": 0,
        "ONLY_TEXT": null,
        "OPTOUT_SOURCE": null,
        "SUBSCRIBE_SOURCE": null,
        "CREATED_DT": "2010-01-29T07:25:00",
        "MODIFIED_DT": null,
        "OPTOUT_DT": null,
        "FIRSTNAME": "Jane 0",
        "ADDRESS_STREET": null,
        "ADDRESS_STREET_NUMBER": null,
        "ADDRESS_STREET_BOX": null,
        "ADDRESS_ZIP_CODE": null,
        "ADDRESS_CITY": null,
        "ADDRESS_COUNTRY": null,
        "PHONE_MOBILE": null,
        "PHONE_FIX": null,
        "BIRTHDAY": null,
        "GENDER": "F",
        "LANG": null,
        "PHONE": null,
        "OPTIN": null,
        "CAMPAIGN": null,
        "MOBILE": null,
        "DESTINATION": null,
        "FRIENDID": null,
        "DISCOUNT": null,
        "CATEGORY": null,
        "PRODUCTS": "\r",
        "COUNTRY_CODE": null,
        "FAVOURITE_BRAND": null,
        "TMP_DATE": null,
        "JGO_TEST": null
    }, ...],
    "total": 170489,
    "_links": [{
        "rel": "next",
        "uri": "/restapi/api/sync/lists/1/profiles?offset=201&size=200",
        "verb": "GET"
    }]
}

A total of 170.489 user records are in the user list. Paging is provided and returns 200 records per page.

All fields in the userlist are returned.

Copy
To limit the scope use the following:
HTTP GET http://someserver.com/restapi/api/sync/lists/1/profiles?fields=id,mail,name,firstname,phone_mobile

 

Read All (streamed)

DESCRIPTION

Use this method to retrieve all user records from a specific user list in streaming. The scope can be limited by specifying the fields in the url of the request.

When including fields from 1:1 relations, which in reality contain 1:n data, multiple records of the same profile are returned.

Key

Profiles-Get-Stream

Path

/restapi/api/stream/lists/{id}/profiles{?fields=x,y,z}

Method

GET

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example of a request without scope limitation:
HTTP GET http://someserver.com/restapi/api/stream/lists/1/profiles
Copy
The result looks like the following (note that each result returned is separated by a line break):
HTTP 200 OK

First result:
{
    "ID": 467345,
    "MAIL": "john.doe126378@planet.nl",
    "NAME": "Doe126378",
    "OPTOUT": 0,
    "TESTUSER": 0,
    "ONLY_TEXT": null,
    "OPTOUT_SOURCE": null,
    "SUBSCRIBE_SOURCE": null,
    "CREATED_DT": "2011-11-23T01:04:15.263",
    "MODIFIED_DT": null,
    "OPTOUT_DT": null,
    "FIRSTNAME": "John 126378",
    "ADDRESS_STREET": null,
    "ADDRESS_STREET_NUMBER": null,
    "ADDRESS_STREET_BOX": null,
    "ADDRESS_ZIP_CODE": null,
    "ADDRESS_CITY": null,
    "ADDRESS_COUNTRY": null,
    "PHONE_MOBILE": null,
    "PHONE_FIX": null,
    "BIRTHDAY": null,
    "GENDER": "M",
    "LANG": null,
    "PHONE": null,
    "OPTIN": null,
    "CAMPAIGN": null,
    "MOBILE": null,
    "DESTINATION": null,
    "FRIENDID": null,
    "DISCOUNT": null,
    "CATEGORY": null,
    "PRODUCTS": "\r",
    "COUNTRY_CODE": null,
    "FAVOURITE_BRAND": null,
    "TMP_DATE": null,
    "JGO_TEST": null
}

 

Copy
Example of a request with scope:
HTTP GET http://someserver.com/restapi/api/stream/lists/1/profiles?fields=id,mail,name
Copy
The first result looks like the following:
{
    "ID": 467345,
    "MAIL": "john.doe126378@planet.nl",
    "NAME": "Doe126378"
}

 

Modify One

DESCRIPTION

Use this method to update an existing user record in a specific user list. It is possible to update data in 1:1 profile extensions as well.

Key

Profiles-Put

Path

/restapi/api/sync/lists/{id}/profiles/{pid}

/restapi/api/async/lists/{id}/profiles/{pid}

Method

PUT

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP PUT http://someserver.com/restapi/api/sync/lists/863/profiles/119 

{
    "Name": "User Test",
    "ActionTriggerlink.ActionId": 1,
    "Extensions.TwitterHandle": "@Suddenelfilio",
    "Domains.MailDomain": "Selligent.be"
}
Copy
The result contains the updated values:
{
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/863/profiles/119",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/863/profiles/119",
        "verb": "PUT"
    }, {
        "rel": "list",
        "uri": "restapi/api/sync/lists/863",
        "verb": "GET"
    }]
}

 

Search (paged)

DESCRIPTION

Use this method to search for a specific profile in a specific user list. The result is depending on the fields in the list and profile extensions, as well as on the filters applied.

When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same profile will be returned

Key

Profiles-Search

Path

/restapi/api/sync/lists/{id}/profiles/search

/restapi/api/async/lists/{id}/profiles/search

Method

POST

Paging support

Yes

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

When performing a search request, it is possible to define the scope of the result by specifying the fields you want to retrieve. The requested fields are separated by a colon.

Copy
The following syntax is used:
{"fields":["id","mail","gender"]}

Note: Because the POST method is used, the parameters are not added to the URL itself but in the payload.

Copy
Example with a scope for ID, Mail, Gender (note that a filter is applied as well):
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search

{
    "fields": ["id", "mail", "gender"],
    "filter": {
        "mail": "somemail@hotmail.com",
        "op": "="
    }
}
Copy
The result looks like the following:
HTTP 200 OK

{
    "result": [{
        "ID": "1",
        "MAIL": "somemail@hotmail.com",
        "GENDER": "M"
    }, {
        "ID": "2",
        "MAIL": "somemail@hotmail.com",
        "GENDER": "F"
    }, {
        "ID": "3",
        "MAIL": "somemail@hotmail.com",
        "GENDER": "F"
    }, {
        "ID": "4",
        "MAIL": "somemail@hotmail.com",
        "GENDER": "F"
    }, {
        "ID": "5",
        "MAIL": "somemail@hotmail.com",
        "GENDER": "M"
    }, {
        "ID": "6",
        "MAIL": "somemail@hotmail.com",
        "GENDER": "M"
    }],
    "total": 6,
    "_links": []
}

When a search is performed, at least one filter is applied on one or more fields

Note: Defining at least one filter is mandatory, else a HTTP 400 bad request will be returned!

Copy
The following syntax is used:
{"fieldname": "filtervalue", "op": "operator"

Where

  • "Fieldname" is the actual name of the field in the list on which the filter is applied.

  • "Filtervalue" is the actual value to filter on for the specified fieldname.

  • "Op" is an indication that what follows is the operator used. This cannot be changed.

  • "Operator" is the actual operator to use. The following operators are supported: <, >, =, >=, <=, <>, Is Null

Copy
Example of a profile search where all fields are retrieved and a filter has been defined on the email address:
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search

{
    "fields": null,
    "filter": {
        "mail": "somemail@hotmail.com",
        "op": "="
    }
}
Copy
The result (partial) of the request is as follows:
HTTP 200 OK

{
    "result": [{
        "ID": 1,
        "MAIL": "somemail@hotmail.com",
        "NAME": "Test 01",
        "OPTOUT": 0,
        "TESTUSER": 1,
        "ONLY_TEXT": null,
        "OPTOUT_SOURCE": null,
        "SUBSCRIBE_SOURCE": null,
        "CREATED_DT": "2010-07-11T16:44:00",
        "MODIFIED_DT": null,
        "OPTOUT_DT": null,
        "GENDER": "M",
        "FIRSTNAME": "John"
    }, ...],
    "total": 13,
    "_links": []
}

The result returns an array of profiles responding to the filter in the request. All available fields in the user list are returned.

Copy
You can also use the operator IS NULL to retrieve for example all profiles without an email:
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search

{
    "fields": null,
    "filter": {
        "mail": "",
        "op": "IS NULL"
    }
}

It is equally possible to combine filters.

By using AND and OR statements multiple filter expressions can be combined. Filters can equally be nested.

Copy
Example:
HTTP POST http: //someserver.com/restapi/api/sync/lists/411/profiles/search
{
    "fields": null,
    "filter": {
        "and": [{
            "mail": "somemail@hotmail.com",
            "op": "="
        }, {
            "gender": "M",
            "op": "="
        }]
    }
}

The filter uses the AND operator to combine two filters, one on the email and one on the gender of the profile.

Copy
The result (partial) is as follows:
HTTP 200 OK

{
    "result": [{
        "ID": 1,
        "MAIL": "somemail@hotmail.com",
        "NAME": "Test 01",
        "OPTOUT": 0,
        "TESTUSER": 1,
        "ONLY_TEXT": null,
        "OPTOUT_SOURCE": null,
        "SUBSCRIBE_SOURCE": null,
        "CREATED_DT": "2010-07-11T16:44:00",
        "MODIFIED_DT": null,
        "OPTOUT_DT": null,
        "GENDER": "M",
        "FIRSTNAME": "John"
    }, {
        "ID": 2,
        "MAIL": "somemail@hotmail.com",
        "NAME": "Test 02",
        "OPTOUT": 1,
        "TESTUSER": 1,
        "ONLY_TEXT": null,
        "OPTOUT_SOURCE": null,
        "SUBSCRIBE_SOURCE": null,
        "CREATED_DT": "2011-02-03T06:50:00",
        "MODIFIED_DT": null,
        "OPTOUT_DT": "2011-02-27T23:02:35",
        "GENDER": "M",
        "FIRSTNAME": "John"
    }, {
        "ID": 4,
        "MAIL": "somemail@hotmail.com",
        "NAME": "Test 03",
        "OPTOUT": 1,
        "TESTUSER": 1,
        "ONLY_TEXT": null,
        "OPTOUT_SOURCE": null,
        "SUBSCRIBE_SOURCE": null,
        "CREATED_DT": "2010-03-16T21:20:00",
        "MODIFIED_DT": null,
        "OPTOUT_DT": "2010-10-08T15:52:51",
        "GENDER": "M",
        "FIRSTNAME": "John"
    }, …],
    "total": 13,
    "_links": []
}

Retrieving information from the 1:1 profile extension and applying filter on these profile extensions is equally possible.

To do so, the name of the profile extension scope must prefix the field name. To retrieve information on profile extensions for a list use the method indicated in section DESCRIPTION.

Copy
Example:
HTTP POST http://someserver.com/restapi/api/sync/lists/411/profiles/search

{
    "fields": ["id", "mail", "gender", "social_linkedin.firstname", "social_linkedin.lastname"],
    "filter": {
        "social_linkedin.firstname": "Filip",
        "op": "="
    }
}

In the above request, the fields 'ID', 'mail' and 'gender' are retrieved from the user list. The fields 'firstname' and 'lastname' are added from the profile extension 'social_linkedin'. A filter is applied on the field 'firstname' in the profile extension.

Copy
The result looks like the following:
{
    "result": [{
        "ID": 14,
        "MAIL": "filip@xxzz.net",
        "GENDER": null,
        "SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
        "SOCIAL_LINKEDIN.LASTNAME": "LeRoi"
    }, ...],
    "total": 11,
    "_links": []
}

 

Search (streamed)

DESCRIPTION

Use this method to search for a specific profile in a specific user list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode.

When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same profile will be returned

Key

Profiles-Search-Streamed

Path

/restapi/api/stream/lists/{id}/profiles/search

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/stream/lists/411/profiles/search
{"fields": ["id", "mail", "gender", "social_linkedin.firstname", "social_linkedin.lastname"], "filter": {"social_linkedin.firstname": "Filip", "op": "="}}
Copy
The result looks like the following:
HTTP 200 OK
    
First result:
{
    "id": 1,
    "MAIL": "filip@yyzz.net",
    "GENDER": null,
    "SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
    "SOCIAL_LINKEDIN.LASTNAME": "LeRoi"
}

Second result:
{
    "id": 2,
    "MAIL": "filip@soemwhat.net",
    "GENDER": "M",
    "SOCIAL_LINKEDIN.FIRSTNAME": "Filip",
    "SOCIAL_LINKEDIN.LASTNAME": "Wuyts"
}

 

Lists Relations

Create One

DESCRIPTION

Use this method to create a list relation. Only 1:1 and 1:N relations can be created. All fields are mandatory. The provided master and slave fields are checked for existence against their respective tables.

Key

Relations-Post

Path

/restapi/api/sync/lists/{id}/relations

/restapi/api/async/lists/{id}/relations

Method

POST

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/sync/lists/868/relations

{
    "master_field": "ID",
    "slave": 131,
    "slave_field": "TESTFIELD_ID",
    "scope": "DATA_TEST_API",
    "name": "DATA_TEST",
    "type": "1:1"
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "id": 15,
    "master": 868,
    "master_field": "ID",
    "slave": 131,
    "slave_field": "TESTFIELD_ID",
    "scope": "DATA_TEST_API",
    "name": "DATA_TEST",
    "type": "1:1",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/868/relations",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/868/relations/15",
        "verb": "PUT"
    }, {
        "rel": "master",
        "uri": "restapi/api/sync/lists/868",
        "verb": "GET"
    }, {
        "rel": "slave",
        "uri": "restapi/api/sync/lists/131",
        "verb": "GET"
    }]
}

The _links section provides insight in all other actions that can be performed on the list relation.

 

Read Many

DESCRIPTION

Use this method to retrieve the relations for one specific list by using the ID of the list

Key

Relations-Get

Path

/restapi/api/sync/lists/{id}/relations

/restapi/api/async/lists/{id}/relations

Method

GET

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a request:
HTTP GET http://someserver.com/restapi/api/sync/lists/1/relations  
Copy
The result looks like the following:
HTTP 200 OK

[{
    "id": 15,
    "master": 1,
    "master_field": "ID",
    "slave": 4,
    "slave_field": "USERID",
    "scope": "EXT_VIRAL_PRODUCTASSIGN",
    "name": "EXT_VIRAL_PRODUCTASSIGN",
    "type": "1:1",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/relations",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/relations/15",
        "verb": "PUT"
    }, {
        "rel": "master",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }, {
        "rel": "slave",
        "uri": "restapi/api/sync/lists/4",
        "verb": "GET"
    }]
},
     ...
]

The result contains an array of relations with information on

  • Id: the id of the relation
  • master: the id of the master list
  • master_field: the fieldname of the master list that links to the slave list
  • slave: the id of the slave list
  • slave_field: the fieldname of the slave list that links to the master list
  • scope: the scope of the list extension
  • name: the name of the list extension
  • type: indicates if this is a 1:1 (profile extension) or 1:n list extension
  • _links: other actions available on relations.

 

Modify One

DESCRIPTION

Use this method to modify a list relation. Fields with no change must be supplied with value ‘null’. The provided master and slave fields are checked for existence against their respective tables. When a slave field is changed, the respective list id must also be provided and vice versa.

Key

Relations-Put

Path

/restapi/api/sync/lists/{id}/relations/15

/restapi/api/async/lists/{id}/relations/15

Method

PUT

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP PUT http://someserver.com/restapi/api/sync/lists/1/relations/520

{
    "id": 520,
    "master_field": null,
    "slave": 131,
    "slave_field": "ANSWER",
    "scope": null,
    "name": null,
    "type": null
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/relations",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/relations/520",
        "verb": "PUT"
    }, {
        "rel": "master",
        "uri": "restapi/api/sync/lists/8",
        "verb": "GET"
    }, {
        "rel": "slave",
        "uri": "restapi/api/sync/lists/131",
        "verb": "GET"
    }]
}

The _links section provides insight in all other actions that can be performed on the list relation.

 

Listfields

DESCRIPTION

Use this method to add a field to the list

Key

ListField-Post

Path

/restapi/api/sync/lists/{ListId}/fields

/restapi/api/async/lists/{ListId}/fields

Method

POST

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP POST http://someserver.com/restapi/api/sync/lists/1/fields

{
    {
        "column": "street",
        "dataType": "text",
        "maxLength": 50,
        "optionlist": 1,
        "required": false
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    {
        "column": "street",
        "primary_key": false,
        "dataType": "text",
        "maxLength": 50,
        "optionlist": 1,
        "required": false
    }, "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/fields/street",
        "verb": "PUT"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/fields/street",
        "verb": "DELETE"
    }, {
        "rel": "options",
        "uri": "restapi/api/sync/optionlists/1",
        "verb": "GET"
    }, {
        "rel": "list",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }]
}

The _links section provides insight in all other actions that can be performed on the list field.

 

Modify One

DESCRIPTION

Use this method to update a listfield

Key

ListField-Put    

Path

/restapi/api/sync/lists/{listid}/fields/{fieldName}

/restapi/api/async/lists/{ listid}/fields/{fieldName}

Method

PUT

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
HTTP PUT http://someserver.com/restapi/api/sync/lists/1/fields/street

{
    {
        "column": "street",
        "dataType": "text",
        "maxLength": 50,
        "optionlist": 1,
        "required": false
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/fields/street",
        "verb": "PUT"
    }, {
        "rel": "self",
        "uri": "restapi/api/sync/lists/1/fields/street",
        "verb": "DELETE"
    }, {
        "rel": "list",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }]
}

The _links section provides insight in all other actions that can be performed on the list schema.

 

Delete One

DESCRIPTION

Use this method to delete a field from a list

Key

ListField-Delete

Path

/restapi/api/sync/lists/{listId}/fields/{fieldName}

/restapi/api/async/lists/{listId}/fields/{fieldName}

Method

DELETE

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a request:
HTTP DELETE http://someserver.com/restapi/api/sync/lists/1/fields/street 
Copy
The result of the request looks like the following:
HTTP 200 OK

{
    "_links": [{
        "rel": "list",
        "uri": "restapi/api/sync/lists/1",
        "verb": "GET"
    }]
}

 

Optionlists

Read One

DESCRIPTION

Use this method to retrieve the option list values for a specific field in a specific list by using the ID of the list. The optionlist ID is required in the request as well and can be obtained from the result returned when retrieving the scheme of that specific list.

Key

Options-Get

Path

/restapi/api/sync/optionlists/{optionlistID}

/restapi/api/async/optionlists/{optionlistID}

Method

GET

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a request:
HTTP GET http://someserver.com/restapi/api/sync/optionlists/232
Copy
The result returned:
HTTP 200 OK

{
    "available_languages": "EN,NL,FR",
    "languages": [{
        "language": "EN",
        "options": [{
            "index": 1,
            "code": "M",
            "value": "Male"
        }, {
            "index": 2,
            "code": "F",
            "value": "Female"
        }]
    }, {
        "language": "FR",
        "options": [{
            "index": 2,
            "code": "F",
            "value": "Femme"
        }, {
            "index": 1,
            "code": "M",
            "value": "Homme"
        }]
    }, {
        "language": "NL",
        "options": [{
            "index": 1,
            "code": "M",
            "value": "Man"
        }, {
            "index": 2,
            "code": "F",
            "value": "Vrouw"
        }]
    }],
    "name": "Gender",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/232",
        "verb": "GET"
    }, {
        "rel": "en-values",
        "uri": "restapi/api/sync/optionlists/232/en",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/232/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/232/fr",
        "verb": "GET"
    }]
}

The result returns

  • available_languages: the language codes that have translations
  • languages: for each language the options will be listed with their translated value
  • index: the location of the option in a list
  • code: the option code
  • value: the translated value for the code.
  • name: the option list name
  • _links:  links other actions available on option lists.

 

To retrieve the option list values for a specific language, simply pass on the language in the URL as well.

Note: The  _links in the result of the request for optionlist values, indicates also what you need to do to retrieve this information.

Copy
Example of a request for English values only:
HTTP GET http://someserver.com/restapi/api/sync/optionlists/232/en
Copy
The result looks like the following:
HTTP 200 OK

{
    "available_languages": "EN,NL,FR",
    "languages": [{
        "language": "EN",
        "options": [{
            "index": 1,
            "code": "M",
            "value": "Male"
        }, {
            "index": 2,
            "code": "F",
            "value": "Female"
        }]
    }],
    "name": "Gender",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/232",
        "verb": "GET"
    }, {
        "rel": "en-values",
        "uri": "restapi/api/sync/optionlists/232/en",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/232/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/232/fr",
        "verb": "GET"
    }]
}

 

Get all optionlists

DESCRIPTION

Use this method to retrieve a list of available optionlists.

Key

OptionLists-Get

Path

/restapi/api/sync/optionlists

/restapi/api/sync/optionlists?offset=1&size=200

Method

GET

Paging support

yes

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

1

300

Copy
Example of a direct request:
HTTP GET http://someserver.com/restapi/api/sync/optionlists
Copy
The result looks like the following:
HTTP 200 OK

{
    "result": [{
        "available_languages": ["EN", "NL"],
        "id": 1,
        "name": "Gender",
        "description": "The possible gender types.",
        "sqlquery": null,
        "_links": [{
            "rel": "self",
            "uri": "restapi/api/sync/optionlists/1",
            "verb": "GET"
        }, {
            "rel": "en-values",
            "uri": "restapi/api/sync/optionlists/1/en",
            "verb": "GET"
        }, {
            "rel": "nl-values",
            "uri": "restapi/api/sync/optionlists/1/nl",
            "verb": "GET"
        }]
    }, {
        "available_languages": ["NL"],
        "id": 3,
        "name": "COMPANY",
        "description": "A list of companies",
        "sqlquery": null,
        "_links": [{
            "rel": "self",
            "uri": "restapi/api/sync/optionlists/3",
            "verb": "GET"
        }, {
            "rel": "nl-values",
            "uri": "restapi/api/sync/optionlists/3/nl",
            "verb": "GET"
        }]
    }],
    "total": 2,
    "_links": []
}

 

Create optionlist (SQL)

DESCRIPTION

Use this method to create an optionlist based on a sqlquery.

Remarks:

  • SqlQuery: only SELECT statements are allowed and max length is 1000. Each language in “available_languages” should have a corresponding column in the query (case sensitive!). “CODE” is also a required column.

  • available_languages: only the languages in the LANGUAGES table in SIM are allowed (case sensitive!)

  • field “languages” is not allow when the “sqlqueryfield” is present.

Key

Options-Post

Path

/restapi/api/sync/optionlists

Method

POST

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP POST http://someserver.com/restapi/api/sync/optionlists

{
    "name": "rest option list",
    "description": "Description here",
    "sqlquery": "SELECT 123 AS CODE, 'eentweedrie' AS NL, 'undeuxtrois' as FR FROM MYCUSTOMOPTIONS"
    "available_languages": "NL,FR"
}
Copy
The result returned by this request looks like this:
HTTP 200 OK

{
    "available_languages": ["NL", "FR"],
    "languages": [{
        "language": "NL",
        "options": [{
            "index": 0,
            "code": "123",
            "value": "eentweedrie"
        }]
    }, {
        "language": "FR",
        "options": [{
            "index": 1,
            "code": "123",
            "value": "undeuxtrois"
        }]
    }],
    "id": 11,
    "name": "rest option list",
    "description": "Description here",
    "sqlquery": " SELECT 123 AS CODE, 'eentweedrie' AS NL, 'undeuxtrois' as FR",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/11",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/11/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/11/fr",
        "verb": "GET"
    }]
}

 

Create optionlist (code)

DESCRIPTION

Use this method to create an optionlist.

Remarks:

  • available_languages: only the languages in the LANGUAGES table in SIM are allowed (case sensitive!)

  • languages: every language in “available_languages” should have options.

  • code: no duplicate codes allowed in a language

Key

Options-Post

Path

/restapi/api/sync/optionlists

Method

POST

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP POST http://someserver.com/restapi/api/sync/optionlists

{
    "name": "rest option list",
    "description": "Description here",
    "available_languages": "NL,FR",
    "languages": [{
        "language": "NL",
        "options": [{
            "code": "code1",
            "value": "value1 NL"
        }, {
            "code": "code2",
            "value": "value2 NL"
        }, {
            "code": "code3",
            "value": "value3 NL"
        }]
    }, {
        "language": "FR",
        "options": [{
            "code": "code1",
            "value": "value1 FR"
        }, {
            "code": "code3",
            "value": "value3 FR"
        }]
    }]
}
Copy
The result returned by this request looks like this:
HTTP 200 OK

{
    "available_languages": ["NL", "FR"],
    "languages": [{
        "language": "FR",
        "options": [{
            "index": 0,
            "code": "code1",
            "value": "value1 fr"
        }, {
            "index": 1,
            "code": "code3",
            "value": "value3 fr"
        }]
    }, {
        "language": "NL",
        "options": [{
            "index": 0,
            "code": "code1",
            "value": "value1 nl"
        }, {
            "index": 1,
            "code": "code2",
            "value": "value2 nl"
        }, {
            "index": 2,
            "code": "code3",
            "value": "value3 nl"
        }]
    }],
    "id": 10,
    "name": "rest option list",
    "description": "Description here",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/10",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/10/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/10/fr",
        "verb": "GET"
    }]
}

 

Update optionlist

DESCRIPTION

Use this method to update an optionlist.

Remarks:

  • Only the fields that need to be updated should be included in the content.

  • Same validation rules apply as in the POST

Key

Options-Post

Path

/restapi/api/sync/optionlists/{id}

Method

PUT

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP PUT http://someserver.com/restapi/api/sync/optionlists/1

{
    "name": "rest option list",
    "description": "Description here",
    "sqlquery": " SELECT 123 AS CODE, 'eentweedrie' AS NL, 'undeuxtrois' as FR FROM MYCUSTOMOPTIONS"
    "available_languages": "NL,FR"
}
Copy
The result returned by this request looks like this:
HTTP 200 OK

{
    "available_languages": ["NL", "FR"],
    "languages": [{
        "language": "FR",
        "options": [{
            "index": 0,
            "code": "code1",
            "value": "value1 fr"
        }, {
            "index": 1,
            "code": "code3",
            "value": "value3 fr"
        }]
    }, {
        "language": "NL",
        "options": [{
            "index": 0,
            "code": "code1",
            "value": "value1 nl"
        }, {
            "index": 1,
            "code": "code2",
            "value": "value2 nl"
        }, {
            "index": 2,
            "code": "code3",
            "value": "value3 nl"
        }]
    }],
    "id": 10,
    "name": "rest option list",
    "description": "Description here",
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/10",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/10/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/10/fr",
        "verb": "GET"
    }]
}

 

Delete optionlist

DESCRIPTION

Use this method to delete an optionlist

Key

Options-Delete

Path

/restapi/api/sync/optionlists/{id}

Method

DELETE

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP DELETE http://someserver.com/restapi/api/sync/optionlists/1
Copy
The result returned by this request looks like this:
HTTP 200 OK

 

Add option

DESCRIPTION

Use this method to add an option to an optionlist.

Remarks:

Returns an error if the optionlist was defined with a sql query

Key

Options-Post-Option

Path

/restapi/api/sync/optionlists/{optionlistId}/options

Method

POST

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP POST http://someserver.com/restapi/api/sync/optionlists/1/options

{
    "code": "code5",
    "languages": [{
        "language": "NL",
        "value": "value1 NL"
    }, {
        "language ": "FR",
        "value": "value1 FR"
    }]
}
Copy
The result returned by this request looks like this:
HTTP 200 OK

{
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/9",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/9/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/9/fr",
        "verb": "GET"
    }]
}

 

Update option

DESCRIPTION

Use this method to update an option in an optionlist.

Remarks:

Returns an error if the optionlist was defined with a sql query

Key

Options-Put-Option

Path

/restapi/api/sync/optionlists/{optionlistId}/options

Method

PUT

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP PUT http://someserver.com/restapi/api/sync/optionlists/1/options

{
    "code": "code5",
    "languages ": [{
            "language ": "NL ",
            "value ": "value1 NL "
        },
        {
            "language ": "FR ",
            "value ": "value1 FR "
        }
    ]
}
Copy
The result returned by this request looks like this:
HTTP 200 OK
    
{
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/sync/optionlists/9",
        "verb": "GET"
    }, {
        "rel": "nl-values",
        "uri": "restapi/api/sync/optionlists/9/nl",
        "verb": "GET"
    }, {
        "rel": "fr-values",
        "uri": "restapi/api/sync/optionlists/9/fr",
        "verb": "GET"
    }]
}

 

Delete option

DESCRIPTION

Use this method to delete an option in an optionlist.

Remarks:

Returns an error if the optionlist was defined with a sql query

Key

Options-Delete-Option

Path

/restapi/api/sync/optionlists/{optionlistId}/options

Method

PUT

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example of a direct request:
HTTP DELETE http://someserver.com/restapi/api/sync/optionlists/1/options

{
    "code": "code5"
}
Copy
The result returned by this request looks like this:
HTTP 200 OK

 

Article lists

Create Article list

DESCRIPTION

Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property.

Key

Lists-post

Path

/restapi/api/sync/lists

/restapi/api/async/lists

Method

POST

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists

Post body:
{
    "name": "ARTICLE_EXAMPLE_LIST",
    "type": "ARTICLELIST",
    "folder": 1964,
    "owner": 279,
    "disabled": 0,
    "fields": [{
        "column": "title",
        "dataType": "text",
        "maxLength": 50,
        "required": true
    }, {
        "column": "description",
        "dataType": "long text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "art_int",
        "dataType": "numeric",
        "required": true
    }, {
        "column": "art_long",
        "dataType": "long",
        "required": false
    }, {
        "column": "art_float",
        "dataType": "float",
        "required": true
    }, {
        "column": "art_datetime",
        "dataType": "datetime",
        "required": true
    }, {
        "column": "art_date",
        "dataType": "date",
        "required": true
    }, {
        "column": "art_boolean",
        "dataType": "boolean",
        "required": false
    }]
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "id": 4177,
    "type": "ARTICLELIST",
    "tablename": "DB_DATA.dbo.ARTICLES_ ARTICLE_EXAMPLE_LIST ",
    "name": " ARTICLE_EXAMPLE_LIST ",
    "description": null,
    "folder": 1964,
    "owner": 279,
    "disabled": 0,
    "fields": [{
        "column": "ID",
        "primary_key": true,
        "required": true,
        "maxlength": 0,
        "optionlist": 0,
        "datatype": "Numeric",
        "_links": [{
            "rel": "self",
            "uri": "restapi/api/async/lists/4177/fields/id",
            "verb": "PUT"
        }, {
            "rel": "self",
            "uri": "restapi/api/async/lists/4177/fields/id",
            "verb": "DELETE"
        }]
    }, …],
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/async/lists/4177",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/async/lists/4177",
        "verb": "PUT"
    }, ]
}

 

Create one article

DESCRIPTION

Use this method to create data for one specific article list entry by providing the desired input. All fields are checked for existence against the article list table.

Key

ArticleList-Post

Path

/restapi/api/sync/lists/{id}/articles

Method

POST

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists/111/articles

Post body:
{
    "title": "art title",
    "ART_INT": 1,
    "ART_FLOAT": 1.25
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "title": "art title",
    "ART_INT": 1,
    "ART_FLOAT": 1.25,
    "CREATED_DT": "2016-10-21T16:15:07.8087164+02:00",
    "Id": 1
}

 

Create many articles (streamed)

DESCRIPTION

Use this method to create data for one or many article list entries by providing the desired input. All fields are checked for existence against the article list table. For this call it is required to provide the fields which will be posted on the first line, pipe-separated.

Key

ArticleList-Post-Stream

Path

/restapi/api/stream/lists/{id}/articles/post?mode=append

Method

POST

Paging support

No

Stream support

Yes

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
POST restapi/api/stream/lists/111/articles/post?mode=append

TITLE|art_int|art_float
{"TITLE": "title", "art_int": 1, "art_float": 1.25}
{"TITLE": "title", "art_int": 2, "art_float": 1.25}
{"TITLE": "title", "art_int": 3, "art_float": 1.25}
{"TITLE": "title", "art_int": 4, "art_float": 1.25}
{"TITLE": "title", "art_int": 5, "art_float": 1.25}
{"TITLE": "title", "art_int": 6, "art_float": 1.25}
{"TITLE": "title", "art_int": 7, "art_float": 1.25}
{"TITLE": "title", "art_int": 8, "art_float": 1.25}
{"TITLE": "title", "art_int": 9, "art_float": 1.25}
{"TITLE": "title", "art_int": 0, "art_float": 1.25}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

No additional content is returned.

 

Delete one article

DESCRIPTION

Use this method to delete a specific article record in a specific article list.

Key

ArticleList-Delete-Id

Path

/restapi/api/{mode}/lists/{id}/articles/{ArticleId}

Method

DELETE

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
DELETE restapi/api/sync/lists/4028/articles/1
Copy
The result returned by the request looks like the following:
HTTP 200 OK

No additional content is returned.

 

Read one article

DESCRIPTION

Use this method to retrieve information on a specific article record in a specific article list.

Key

ArticleList-Get-Id

Path

/restapi/api/{mode}/lists/{id}/articles/{articleId}

Method

GET

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
GET restapi/api/sync/lists/4028/articles/1
Copy
The result of the request looks like the following:
HTTP 200 OK

{
    "ID": 1,
    "CREATED_DT": "2016-10-21T16:15:07.81",
    "MODIFIED_DT": null,
    "TAXONOMY": null,
    "TITLE": "art title",
    "ART_INT": 1,
    "ART_FLOAT": 1.25,
}

 

Read all articles (paged)

DESCRIPTION

Use this method to retrieve multiple article records in a specific article list.

Key

ArticleList-Get

Path

/restapi/api/{mode}/lists/{id}/articles

Method

GET

Paging support

YES

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
GET api/sync/lists/4028/articles?offset=5&size=2
Copy
The result of the request is as follows:
HTTP 200 OK

{
    "result": [{
        "ID": 5,
        "CREATED_DT": "2016-10-14T16:22:12.05",
        "MODIFIED_DT": null,
        "TAXONOMY": null,
        "TITLE": "title",
        "DESCRIPTION": null,
        "ART_INT": 4,
        "ART_LONG": null,
        "ART_FLOAT": 1.25,
        "ART_DATETIME": null,
        "ART_DATE": null,
        "ART_BOOLEAN": null
    }, {
        "ID": 6,
        "CREATED_DT": "2016 - 10 14 T16: 22: 12.05",
        "MODIFIED_DT": null,
        "TAXONOMY": null,
        "TITLE": "title ",
        "DESCRIPTION": null,
        "ART_INT": 5,
        "ART_LONG": null,
        "ART_FLOAT": 1.25,
        "ART_DATETIME": null,
        "ART_DATE": null,
        "ART_BOOLEAN": null
    }],
    "total": 9,
    "_links": [{
        "rel": "prev",
        "uri": "restapi/api/sync/lists/4028/articles?offset=3&size=2",
        "verb": "GET"
    }, {
        "rel": "next",
        "uri": "restapi/api/sync/lists/4028/articles?offset=7&size=2",
        "verb": "GET"
    }]
}

 

Read all articles (streamed)

DESCRIPTION

Use this method to retrieve all article records in a specific article list.

Key

ArticleList-Get-Stream

Path

/restapi/api/stream/lists/{id}/articles

Method

GET

Paging support

NO

Stream support

YES

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
GET restapi/api/stream/lists/4028/articles
Copy
The result looks like the following (note that each result returned is separated by a line break):
HTTP 200 OK

First result:
{
    "ID": 1,
    "CREATED_DT": "2016-10-14T16:22:02.373",
    "MODIFIED_DT": null,
    "TAXONOMY": null,
    "TITLE": "arttitle",
    "DESCRIPTION": null,
    "ART_INT": 1,
    "ART_LONG": null,
    "ART_FLOAT": 1.25,
    "ART_DATETIME": null,
    "ART_DATE": null,
    "ART_BOOLEAN": null
}

 

Modify one article

DESCRIPTION

Use this method to update an article

Key

ArticleList-Put-Id

Path

/restapi/api/sync/lists/{id}/articles/{articleId}

/restapi/api/async/lists/{id}/articles/{articleId}

Method

Put

Paging support

NO

Stream support

NO

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
PUT restapi/api/sync/lists/4028/articles

Put body:
{
    "title": "art updated",
    "ART_DATETIME": "2016-10-20T16:22:12.05"
}
The result of the request is as follows:
HTTP 200 OK

 

Search (paged)

DESCRIPTION

Use this method to search for a specific article in a specific article list. The result is depending on the fields in the list and  extensions, as well as on the filters applied.

When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same article will be returned

Key

ArticleList-Search

Path

/restapi/api/sync/lists/{id}/articles/search

/restapi/api/async/lists/{id}/articles/search

Method

POST

Paging support

Yes

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST http://someserver.com/api/sync/lists/411/articles/search

Post body:
{
    "fields": ["id", "title", "content"],
    "filter": {
        "title": "some title",
        "op": "="
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "result": [{
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }, {
        "ID": "2",
        "TITLE": "some title",
        "CONTENT": "some text"
    }, {
        "ID": "3",
        "TITLE": "some title",
        "CONTENT": "some text"
    }],
    "total": 3,
    "_links": []
}

Rest is the same as “Search Paged in List Profiles

 

Search (streamed)

DESCRIPTION

Use this method to search for a specific article in a specific article list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode.

When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same article will be returned.

Key

ArticleList-Search-Streamed

Path

/restapi/api/stream/lists/{id}/articles/search

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
POST http://someserver.com/api/stream/lists/411/articles/search

Post body:
{
    "fields": ["id", "title", "content"],
    "filter": {
        "title": "some title",
        "op": "="
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

First result:
{
    {
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }
}

Second result:
{
    {
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }
}

 

Product lists

Create Product list

DESCRIPTION

Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property.

Key

Lists-post

Path

/restapi/api/sync/lists

/restapi/api/async/lists

Method

POST

Paging support

NO

Stream support

NO

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists

Post body:
{
    "name": "PROD_EXAMPLE_LIST",
    "type": "PRODUCTLIST",
    "folder": 1964,
    "owner": null,
    "fields": [{
        "column": "title",
        "dataType": "text",
        "maxLength": 50,
        "required": true
    }, {
        "column": "description",
        "dataType": "long text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "prod_int",
        "dataType": "numeric",
        "maxLength": 50,
        "required": true
    }, {
        "column": "prod_long",
        "dataType": "long",
        "required": false
    }, {
        "column": "prod_float",
        "dataType": "float",
        "required": true
    }, {
        "column": "prod_datetime",
        "dataType": "datetime",
        "required": true
    }, {
        "column": "prod_date",
        "dataType": "date",
        "required": true
    }, {
        "column": "prod_boolean",
        "dataType": "boolean",
        "required": false
    }]
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "id": 4182,
    "type": "PRODUCTLIST",
    "tablename": "DB_DATA.dbo.PRODUCTS_PROD_EXAMPLE_LIST",
    "name": "PROD_EXAMPLE_LIST",
    "description": null,
    "folder": 1964,
    "owner": 279,
    "disabled": null,
    "fields": [{
            "column": "ID",
            "primary_key": true,
            "required": true,
            "maxlength": 0,
            "optionlist": 0,
            "datatype": "Numeric"
        },
        ...
    ],
    "_links ": [{
        "rel": "self ",
        "uri ": "restapi/api/async/lists/4182",
        "verb ": "GET "
    }, {
        "rel ": "self ",
        "uri": "restapi/api/async/lists/4182",
        "verb": "PUT "
    }]
}

 

Create one product

DESCRIPTION

Use this method to create data for one specific product list entry by providing the desired input. All fields are checked for existence against the product list table.

Key

ProductList-post

Path

/restapi/api/sync/lists/{id}/products

Method

POST

Paging support

NO

Stream support

NO

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists/4022/products

Post body:
{
    "title": "prod title",
    "prod_int": 1,
    "prod_float": 1.25
}
Copy
The result returned by the request looks like the following:
HTTP 200  OK 

{
    "title": "prod title",
    "prod_int": 1,
    "prod_float": 1.25,
    "CREATED_DT": "2016-10-21T16:34:34.9240738+02:00",
    "Id": 2
}

 

Create many products (streamed)

DESCRIPTION

Use this method to create data for one or many product list entries by providing the desired input. All fields are checked for existence against the product list table.

For this call it is required to provide the fields which will be posted on the first line, pipe-separated.

Key

ProductList-Post-Stream

Path

/restapi/api/stream/lists/{id}/products/post?mode=append

Method

POST

Paging support

NO

Stream support

YES

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
POST restapi/api/stream/lists/4022/products/post?mode=append

TITLE|prod_int|prod_float
{"TITLE": "title", "prod_int": 1, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 2, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 3, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 4, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 5, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 6, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 7, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 8, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 9, "prod_float": 1.25}
{"TITLE": "title", "prod_int": 0, "prod_float": 1.25}
The result returned by the request looks like the following:
HTTP 200 OK

No additional content is returned.

 

Delete one product

DESCRIPTION

Use this method to delete a specific product record in a specific product list.

Key

ProductList-Delete-Id

Path

/restapi/api/{mode}/lists/{id}/products/{productId}

Method

DELETE

Paging support

NO

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

1000

0

300

Copy
Example:
DELETE restapi/api/sync/lists/4028/products/1
The result returned by the request looks like the following:
HTTP 200 OK 

No additional content is returned.

 

Read one product

DESCRIPTION

Use this method to retrieve information on a specific product record in a specific product list.

Key

ProductList-Get-Id

Path

/restapi/api/{mode}/lists/{id}/products/{productId}

Method

Get

Paging support

NO

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

1000

0

300

Copy
Example:
GET restapi/api/sync/lists/4028/products/1
Copy
The result of the request looks like the following:
HTTP 200 OK

{
    "ID": 1,
    "CREATED_DT": "2016-10-21T16:34:07.513",
    "TITLE": "prod title",
    "DESCRIPTION": null,
    "PROD_INT": 1,
    "PROD_LONG": null,
    "PROD_FLOAT": 1.25,
}

 

Read all products (paged)

DESCRIPTION

Use this method to retrieve multiple product records in a specific article list.

Key

ProductList-Get

Path

/restapi/api/{mode}/lists/{id}/products

Method

Get

Paging support

YES

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

1000

0

300

Copy
Example:
GET restapi/api/sync/lists/4028/products?offset=5&size=2
Copy
The result of the request is as follows:
HTTP 200 OK 

{
    "result": [{
        "ID": 5,
        "CREATED_DT": "2016-10-14T16:22:30.67",
        "MODIFIED_DT": null,
        "TITLE": "title",
        "DESCRIPTION": null,
        "PROD_INT": 4
    }],
    "total": 11,
    "_links": [{
        "rel": "prev",
        "uri": "restapi/api/sync/lists/4029/products?offset=3&size=2",
        "verb": "GET"
    }, {
        "rel": "next",
        "uri": "restapi/api/sync/lists/4029/products?offset=7&size=2",
        "verb": "GET"
    }]
}

 

Read all products (streamed)

DESCRIPTION

Use this method to retrieve all products records in a specific product list.

Key

ProductList-Get-Stream

Path

/restapi/api/stream/lists/{id}/products

Method

Get

Paging support

No

Stream support

YES

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
GET restapi/api/stream/lists/4028/products
Copy
The result looks like the following (note that each result returned is separated by a line break):
HTTP 200 OK 

First result :
{
    "ID": 1,
    "CREATED_DT": "2016-10 14T16:22:18.553",
    "MODIFIED_DT": null,
    "AVAILABLE_DT": null,
    "RESERVED_DT": null,
    "LOCK_DT": null,
    "LOCK_TOKEN": null,
    "ITEMTYPE": null,
    "CAMPAIGNID": null,
    "ACTIONID": null,
    "LISTID": null,
    "USERID": null,
    "TITLE": "prod title",
    "DESCRIPTION": null,
    "PROD_INT": 1,
    "PROD_LONG": null,
    "PROD_FLOAT": 1.25,
    "PROD_DATETIME": null,
    "PROD_DATE": null,
    "PROD_BOOLEAN": null
}

 

Modify one product

DESCRIPTION

Use this method to update a product

Key

ProductList-Put-Id

Path

/restapi/api/sync/lists/{id}/products/{productId}

/restapi/api/async/lists/{id}/products/{productId}

Method

Put

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
PUT restapi/api/sync/lists/4028/products

Put body:
{
    "title": "product updated",
    "PROD_DATETIME": "2016-10-20T16:22:12.05"
}
The result of the request is as follows:
HTTP 200 OK

 

Search (Paged)

DESCRIPTION

Use this method to search for a specific product in a specific product list. The result is depending on the fields in the list and  extensions, as well

as on the filters applied. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same product will be returned.

Key

ProductList-Search

Path

/restapi/api/sync/lists/{id}/products/search

/restapi/api/async/lists/{id}/products/search

Method

POST

Paging support

Yes

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST http://someserver.com/api/sync/lists/411/products/search

Post body:
{
    "fields": ["id", "title", "content"],
    "filter": {
        "title": "some title",
        "op": "="
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "result": [{
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }, {
        "ID": "2",
        "TITLE": "some title",
        "CONTENT": "some text"
    }, {
        "ID": "3",
        "TITLE": "some title",
        "CONTENT": "some text"
    }],
    "total": 3,
    "_links": []
}

Rest is the same as “Search Paged in List Profiles

 

Search (streamed)

DESCRIPTION

Use this method to search for a specific product in a specific product list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode.

When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same product will be returned.

Key

ProductList-Search-Streamed

Path

/restapi/api/stream/lists/{id}/products/search

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
POST http://someserver.com/api/stream/lists/411/products/search

Post body:
{
    "fields": ["id", "title", "content"],
    "filter": {
        "title": "some title",
        "op": "="
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

First result:
{
    {
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }
}

Second result:
{
    {
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }
}

 

Data list

Create a data list

DESCRIPTION

Use this method to create the metadata for one specific list by providing the required input. You can specify custom fields in this list by using the "fields" property.

Key

Lists-post

Path

/restapi/api/sync/lists

/restapi/api/async/lists

Method

Post

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists

Post body:
{
    "name": "EXAMPLE_DATA_LIST",
    "type": "DATALIST",
    "folder": 1964,
    "owner": null,
    "fields": [{
        "column": "title",
        "dataType": "text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "description",
        "dataType": "long text",
        "maxLength": 50,
        "required": false
    }, {
        "column": "data_int",
        "dataType": "numeric",
        "maxLength": 50,
        "required": false
    }]
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "id": 4266,
    "type": "DATALIST",
    "tablename": "DB_DATA.dbo.DATA_EXAMPLE_DATA_LIST",
    "name": "EXAMPLE_DATA_LIST",
    "description": null,
    "folder": 1964,
    "owner": 279,
    "disabled": null,
    "fields": [{
        "column": "ID",
        "primary_key": true,
        "required": true,
        "maxlength": 0,
        "optionlist": 0,
        "datatype": "Numeric"
    }, {
        "column": "title",
        "primary_key": false,
        "required": false,
        "maxlength": 50,
        "optionlist": 0,
        "datatype": "Text"
    }, {
        "column": "description",
        "primary_key": false,
        "required": false,
        "maxlength": 50,
        "optionlist": 0,
        "datatype": "Long Text"
    }, {
        "column": "data_int",
        "primary_key": false,
        "required": false,
        "maxlength": 50,
        "optionlist": 0,
        "datatype": "Numeric"
    }],
    "_links": [{
        "rel": "self",
        "uri": "restapi/api/async/lists/4266",
        "verb": "GET"
    }, {
        "rel": "self",
        "uri": "restapi/api/async/lists/4266",
        "verb": "PUT"
    }]
}

 

Create one data record

DESCRIPTION

Use this method to create data for one specific data list entry by providing the desired input. All fields are checked for existence against the data list table.

Key

DataList-post

Path

/restapi/api/sync/lists/{id}/data

Method

Post

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST restapi/api/sync/lists/111/data

Post body:
{
    "title": "data title",
    "data_int": 1
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "data_int": 1,
    "Id": 2
}

 

Create many data records (streamed)

DESCRIPTION

Use this method to create data for one or many data list entries by providing the desired input. All fields are checked for existence against the data list table.

For this call it is required to provide the fields which will be posted on the first line, pipe-separated.

Key

DataList-post-stream

Path

/restapi/api/stream/lists/{id}/data/post?mode=append

Method

Post

Paging support

No

Stream support

YES

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
POST restapi/api/stream/lists/111/data/post?mode=append

TITLE|data_int
{"TITLE": "title 1", "data_int": "1"}
{"TITLE": "title 2", "data_int": "2"}
{"TITLE": "title 2", "data_int": "3"}
{"TITLE": "title 4", "data_int": "4"}
{"TITLE": "title 5", "data_int": "5"}
{"TITLE": "title 6", "data_int": "6"}
{"TITLE": "title 7", "data_int": "7"}
{"TITLE": "title 8", "data_int": "8"}
{"TITLE": "title 9", "data_int": "9"}
{"TITLE": "title 10", "data_int": "10"}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

No additional content is returned.

 

Delete one data record

DESCRIPTION

Use this method to delete a specific data record in a specific data list.

Key

DataList-Delete-Id

Path

/restapi/api/{mode}/lists/{id}/data/{dataId}

Method

Delete

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
DELETE restapi/api/sync/lists/4028/data/1
Copy
The result returned by the request looks like the following:
HTTP 200 OK

No additional content is returned.

 

Read one data record

DESCRIPTION

Use this method to retrieve information on a specific data record in a specific data list.

Key

DataList-Get-Id

Path

/restapi/api/{mode}/lists/{id}/data/{dataId}

Method

GET

Paging support

No

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
GET restapi/api/sync/lists/4028/data/12
Copy
The result of the request looks like the following:
HTTP 200 OK

{
    "ID": 12,
    "TITLE": "title 10",
    "DESCRIPTION": null,
    "DATA_INT": 10
}

 

Read all data records (paged)

DESCRIPTION

Use this method to retrieve multiple data records in a specific data list.

Key

DataList-Get

Path

/restapi/api/{mode}/lists/{id}/data

Method

GET

Paging support

YES

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
GET restapi/api/sync/lists/4266/data?offset=5&size=2
Copy
The result of the request is as follows:
HTTP 200 OK

{
    "result": [{
        "ID": 6,
        "TITLE": "title 4",
        "DESCRIPTION": null,
        "DATA_INT": 4
    }, {
        "ID": 7,
        "TITLE": "title 5",
        "DESCRIPTION": null,
        "DATA_INT": 5
    }],
    "total": 11,
    "_links": [{
        "rel": "prev",
        "uri": "restapi/api/sync/lists/4266/data?offset=3&size=2",
        "verb": "GET"
    }, {
        "rel": "next",
        "uri": "restapi/api/sync/lists/4266/data?offset=7&size=2",
        "verb": "GET"
    }]
}

 

Read all data records (streamed)

DESCRIPTION

Use this method to retrieve multiple data records in a specific data list.

Key

DataList-Get

Path

/restapi/api/{mode}/lists/{id}/data

Method

GET

Paging support

YES

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy

Example:

GET restapi/api/stream/lists/4028/data
Copy
The result looks like the following (note that each result returned is separated by a line break):
HTTP 200 OK 

First result:
{
    "ID": 2,
    "TITLE": "data title",
    "DESCRIPTION": null,
    "DATA_INT": 1
}

 

Modify one data record

DESCRIPTION

Use this method to update a data record. When updating multiple columns of a record of which one or more are non-existing columns, the REST API call will succeed and all existing columns will be updated. Non-existing columns are ignored.

Key

DataList-Put-Id

Path

/restapi/api/sync/lists/{id}/data/{dataId}

/restapi/api/async/lists/{id}/data/{dataId}

Method

Put

Paging support

NO

Stream support

NO

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
PUT restapi/api/sync/lists/4028/data

Put body:
{
    "title": "data updated",
    "DATA_INT": 2016
}
The result of the request is as follows:
HTTP 200 OK

 

Search (paged)

DESCRIPTION

Use this method to search for a specific record in a specific data list. The

result is depending on the fields in the list and extensions, as well

as on the filters applied. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same record will be returned

Key

DataList-Search

Path

/restapi/api/sync/lists/{id}/data/search

/restapi/api/async/lists/{id}/data/search

Method

POST

Paging support

Yes

Stream support

No

Quota

Sync

Async

Stream

Life in seconds

25

100

0

300

Copy
Example:
POST http://someserver.com/api/sync/lists/411/data/search

Post body:
{
    "fields": ["id", "title", "content"],
    "filter": {
        "title": "some title",
        "op": "="
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

{
    "result": [{
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }, {
        "ID": "2",
        "TITLE": "some title",
        "CONTENT": "some text"
    }, {
        "ID": "3",
        "TITLE": "some title",
        "CONTENT": "some text"
    }],
    "total": 3,
    "_links": []
}

Rest is the same as “Search Paged in List Profiles

 

Search (streamed)

DESCRIPTION

Use this method to search for a specific record in a specific data list but without buffering the response. The same functionalities are available as when performing this request in asynchronous or synchronous mode. When including fields from 1:1-relations which in reality contain 1:N-data, multiple records of the same record will be returned

Key

DataList-Search-Streamed

Path

/restapi/api/stream/lists/{id}/data/search

Method

POST

Paging support

No

Stream support

Yes

Quota

Sync

Async

Stream

Life in seconds

0

0

1

300

Copy
Example:
POST http://someserver.com/api/stream/lists/411/data/search

Post body:
{
    "fields": ["id", "title", "content"],
    "filter": {
        "title": "some title",
        "op": "="
    }
}
Copy
The result returned by the request looks like the following:
HTTP 200 OK

First result:
{
    {
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }
}

Second result:
{
    {
        "ID": "1",
        "TITLE": "some title",
        "CONTENT": "some text"
    }
}

 

Lists Segments

Read One

DESCRIPTION

Use this method to retrieve data for one specific list segment by using the ID of the list and segment.

Key

Lists-Segments-Get-Id

Path

/restapi/api/sync/lists/{id}/segments/{id}

/restapi/api/async/lists/{id}/segments/{id}

Method

GET

Paging support

No

Stream support

No

Direct request support

Yes. Use 'sync' in the url path for direct requests, use 'async' for queued requests.

Quota