How to Use Ecnow_data API Database.php End Point in ContactNow

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

API ecnow_data are used to create, read and update dataset records, from outside the standard ContactNow agent or admin interface.

To create access tokens for the ContactNow API, you will need to create a case with 8x8 Technical Support to obtain an API username and key. Once you have the username and key, you can use the instructions on the following link to create a token for using the API functionality. ContactNow API Access.

Note: 8x8 does not provide programming support for the ContactNow API. However, further API reference material is linked in the Documentation section at the bottom of this article.

Access the ContactNow API URL

To access any ContactNow API interface, requests need to have an access token. The token will authorize requests for a particular account for a fixed period of time. By default, these requests are restricted to the internet address that requests the token.

The API url to manage these records is

https://api.contactnow.8x8.com/database.php?token=[Token]&method=ecnow_data&action=[Action]&format=[Format]&raw=1

The ecnow_data API has a number of available functions. The request arguments should be passed as HTTP Post or Get variables. The payload / response from the API can be formatted in either json or xml format. The default is json but this can be modified by the format argument below:

Format: xml or json

The API will output a number of optional values depending on the request made.

Success: This shows whether the request succeeded. It will contain a true or false value for json or a 1 or 0 for xml.
Account ID: This shows the authenticated account that ran the API call.
Total: Number of records affected.
Bad: Number of records that failed.
Key: the uniqueue ID that is returned when creating a new record.
Error: If the request failed, this field will contain a description of the fault.
Example of JSON Response:

{"success":true,
"account_id":"10278",
"total":1,
"bad":0,
"key":0}

Example of XML Response:

<result>
    <success>1</success> 
    <account_id>1234</account_id> 
    <total>1</total>
    <bad>0</bad> 
    <key>0</key>
</result>

To create a record using database.php endpoint

This will create a new record and return its success state and a unique key or any errors in the request. If the record already exists it will add new record with the current details resulting in duplicate records.

HTTP Request: POST
Method: ecnow_data
Action: create
Arguments: raw, format
Payload: dataset, ddi_home (optional), ddi_mobile (optional), ddi_work (optional) (note: at least one ddi should be entered), address1 (2)(3)(4) (optional) postcode (optional), firstname (optional), lastname (optional), title (optional), <custom_fields> (optional)

POST API call with json:

database.php?token=[Token]&format=json&method=ecnow_data&action=create&raw=1

json Pay Load:

[{"title":"Mr",
"firstname":"Joe",
"lastname":"Blogs",
"ddi_mobile":"07123456789",
"dataset":"100",
"company_name":"Company Name"}]

The Response:

{"success":true,
"account_id":"10278",
"total":1,
"bad":0,
"key":550423}

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<easycall>
    <ecnow_data>
        <title>Mr</title>
        <firstname>Joe</firstname>
        <lastname>Blogs</lastname>
        <ddi_mobile>07123456789</ddi_mobile>
        <ddi_home />
        <ddi_work />
        <dataset>100</dataset>
        <company_name>Company Name</company_name>
    </ecnow_data>
</easycall>

The Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
    <total>1</total>
    <bad>0</bad>
    <key>550423</key>
</result>

Reading a dataset using database.php endpoint

Read the data/records of a dataset.

HTTP Request: GET
Method: ecnow_data
Action: read
Arguments: urn (uid) (optional), outcome (match outcome code or comma-separated list of outcome codes) (optional), format, dataset

Example:

https://api.contactnow.8x8.com/database.php?token=[Token]&format=json&method=ecnow_data&action=read&dataset=100&raw=1

json Response:

{"success":true,
"total":2,
"list":[
    {"uid":"550423",
    "dataset":"100",
    "agentid":"0",
    "ddi_home":"",
    "ddi_mobile":"07123456789",
    "ddi_work":"",
    "callback":"0000-00-00 00:00:00",
    "urn":null,
    "vendor_urn":null,
    "title":"Mr",
    "firstname":"Joe",
    "lastname":"Blogs",
    "address1":"",
    "address2":"",
    "address3":"",
    "address4":"",
    "address5":"",
    "address6":"",
    "postcode":"",
    "sourcefile":"api_data_100.dat",
    "loaddate":"2019-01-07",
    "outcomecode":"100",
    "notes":"",
    "processdate":"0000-00-00 00:00:00",
    "call_back_notes":"",
    "company_name":"Company Name",
    "test_field":""}
]}

xml Response:

<?xml version="1.0" encoding="utf-8" ?>
<result>
    <success>1</success>
    <total>2</total>
    <list>
        <ecnow_data>
            <uid>550423</uid>
            <dataset>100</dataset>
            <agentid>0</agentid>
            <ddi_home />
            <ddi_mobile>07123456789</ddi_mobile>
            <ddi_work />
            <callback>0000-00-00 00:00:00</callback>
            <urn></urn>
            <vendor_urn></vendor_urn>
            <title>Mr</title>
            <firstname>Joe</firstname>
            <lastname>Blogs<lastname>
            <address1 />
            <address2 />
            <address3 />
            <address4 />
            <address5 />
            <address6 />
            <postcode />
            <sourcefile>api_data_100.dat</sourcefile>
            <loaddate>2019-01-07</loaddate>
            <outcomecode>100</outcomecode>
            <notes />
            <processdate>0000-00-00 00:00:00</processdate>
            <call_back_notes />
            <company_name>Company Name</company_name>
        </ecnow_data>
    </list>
</result>

To update a record using database.php endpoint

This will update an existing record and return its success state or any errors in the request.

HTTP Request: POST
Method: ecnow_data
Action: update
Arguments: raw, format
Payload: uid, dataset, ddi_home (optional), ddi_mobile (optional), ddi_work (optional) (note: at least one ddi should be entered), address1 (2)(3)(4) (optional) postcode (optional), firstname (optional), lastname (optional), title (optional), <custom_fields> (optional)

POST API call with json:

database.php?token=[Token]&format=json&method=ecnow_data&action=update&raw=1

json Pay Load:

[{"uid":"550415",
"dataset":"100",
"company_name":"Company"}]

The Response:

{"success":true,
"account_id":"10278",
"total":1,
"bad":0,
"key":0}

xml Pay Load:

<?xml version='1.0' encoding='utf-8' ?>
<dxi>
    <uid>550415</uid>
    <dataset>100</dataset>
    <company_name>Company</company_name>
</dxi>

The Response:

<result>
    <success>1</success>
    <account_id>10278</account_id>
    <total>1</total>
    <bad>0</bad>
    <key>0</key>
</result>

Documentation

The following 8x8 ContactNow API reference material is available to the public. Each link will open a new browser tab: