sonish-APIDocument-230317-1008-18

Version 2.1 by sonish on 2017/04/03 16:25

Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

API Document

ONEcount REST API Developer's Guide
Version 2.1

Introduction
ONEcount REST API provides different functionality to accomplish many integration related tasks. This API can be used to lookup, create and updated different ONEcount resources which are listed below.
REST takes advantage of the HTTP request methods to layer itself into the existing HTTP architecture. These operations consist of the following:
1. GET - Used for lookup of resources
1. PUT - Used to update a resource
2. POST - Used to create a new resource
ONEcount API provides following functionalities:
1. Lookup

2. Create

3. Update

4. List

User lookup Transaction lookup Question lookup Source code lookup Product lookup
Term lookup
Resource lookup
Add a user/demo
Add a question
Add user transaction
Add source code
Add Product
Add Term
Add Resource
Stats – Telemarketing
Update a user/demo Update a question Update source code Update product Update term
Update resource
ListQuestionsListSourceCodes

1. Attach
Attach resource to product

REST API URL: https://api.onecount.net/v2/
Appkey: THIS WILL BE PROVIDED

Function
The ONEcount REST API will be used to create, update & lookup users, transactions and questions e.t.c. in ONEcount hosted install of the client.
Accessing API
Your HTTP requests to a REST API resource should contain the following information: An HTTP method GET, POST, PUT.
An Appkey sent as Appkey header in the http request to authenticate the request.
Resource name in the url (/resourcename)
Any JSON data or JSON files containing information needed for requests, such as updating a record with new information.
Request
The request data in POST (for create and update) will consist of request parameters required by each method in JSON format. Value of resource will determine which resource is being requested and the access method will determine whether you are trying to create, update or lookup that resource.
For lookup, the parameter list will be part of the request url.

Response
API will output the response in a JSON format discussed below.
{
"result": { "success": "1", "error": { "code": "0", "message": ""
}
},
"Users": {
"Id": "12562", "PartnerId": "5467", "Demo": {
"6": "Sundeep", "7": "Dangol"
}
}
}
The result of the api request will be determined by the value of the success property of result object. Here the value of success will either be 1(true) or 0 (false) depending on whether the requested action succeed.

If value of success is 0 then an error will be generated inside the result object. Code property will have an error code. message property will have the details about the error. This value might be used to display the error in the client application. The response will always have a result object in it plus the individual response listed for each method.
If the value of success is 1 then the response parameters of the called method will also be output. Example: Get list of questions from api
curl -X GET -H "Appkey: xxx" https://api.onecount.net/v2/questions
{
"result": { "success": "1", "error": {
"code": "0",
"message": ""
}
},
"Questions": [
{
"Id": "6",
"Text": "First Name", "Type": "1",
"Alias": "FName"
},
{
"Id": "7",
"Text": "Last Name", "Type": "1",
"Alias": "LName"
},
{
"Id": "5",
"Text": "Specialty", "Type": "5",
"Alias": "specialty all", "Choices": [
{

},
{

}
]}]}
"Id": "123",
"Text": "Physician", "Value": "PH", "Order": "1", "QuestionId": "5"

"Id": "124",
"Text": "Nurse Practioner", "Value": "NP",
"Order": "2", "QuestionId": "5"

Resources
Resources are the available entities that can be accessed/modified via API. Each resource can be created, updated or requested by using the corresponding http method described above.
questions users products terms resources sources transactions
Questions
This resource is for manipulating questions resource. Questions in ONEcount means any question that is asked to the subscriber. It could be anyquestions that appears on customer forms or print forms that gets answered by a subscriber. Questions api call will allow creation, update and search of question in ONEcount. To add a new questions to the system you'll make a POST api call to the questions resource.
The data that is sent should be in JSON format and of type questions as described in References section. The type property of questions object is described below. Questions object will only need a choices block if the question is a multiple choice question(type=4 or 5 or 6)
There can be 6 types of questions:

Type	Description
1	Textbox type questions or short response type question. The response length needs to be less than 255 characters.
2	Textarea type question or long response type question.
3	Password type question. This is basically same as type 1 but when displayed in ONEcount frontend forms typed characters appears as *.
4	Select or dropdown type questions. This is a multiple choice, 1 response type question. When creating this type of question the choices block also needs to be part of the questions object that will hold the possible choices of the select question.
5	Radio button type question. This is a multiple choice, 1 response type question. When creating this type of question the choices block also needs to be part of the questions object that will hold the possible choices of the radio question.
6	Checkbox type question. This is a multiple choice, multi response type question. When creating this type of question the choices block also needs to be part of the questions object that will hold the possible choices of the checkbox question.

Method	Url	Action
GET	/questions	List all questions
GET	/questions/1	Returns question id 1
GET	/questions/lookup?Text=Email	Returns all questions with "Email" in question text
POST	/questions	Create a new question JSON of the Questions type object needs to be sent as post data. Id field should not be sent.
PUT	/questions	Update a question JSON of the Questions type object needs to be sent as post data. Id field is mandatory for update.

GET method can be used to lookup questions.

Request	Type	Description
Lookup params	String	URL encoded key value string parameters for the question that a user is trying to search. Params: Text: Word or phrase that should be present in the question text (String) Type: Look up the question type.

Response	Type	Description
Questions	Questions	Returns found question details.

POST method should be used to create questions. The data that is sent should be in JSON format and of type questions as described in references section. Questions object will only need a choices block if the question is a multiple choice question (type=4 or 5 or 6).

Request	Type	Description
Questions	Questions	This defines the question contents and possible responses.

Response	Type	Description
QuestionId	Int	Returns ONEcount question id on successful creation of the question.

PUT method should be used to update question.

Request	Type	Description
Questions	Questions	This defines the question contents and responses.

Response	Type	Description
QuestionId	Int	Returns ONEcount question id on successful update of the question.

Unknown macro: unmigrated-wiki-markup. Click on this message for details.

GET	/users	Get users data limiting 25.
GET	/users/1	Get data for user id 1. The user id can be a numeric value or a hash
GET	/users/lookup?1=user1@ email.com&return=1,2	Lookup for user whose question id (1) is equal to supplied value. The users object returned will have value of questions 1 & 2. Here for example assumed to be firstname and last name. Return parameter defines a csv of question id that are requested back in response.
POST	/users	Create a new users Parameters required to create the user needs to be sent as post data in JSON format.
PUT	/users/1	Update user id 1. The user id can be a numeric value or a hash Parameters required to update the user needs to be sent as post data in JSON format.
GET	/users/1/partners/2	Get user id 1 and partner id 2's ONEcount hash. The user id can be a numeric value or a hash.
POST	/users/login	Check to see user exist with username/email and password. Parameters required to create JSON object with u as username, e as email and p as password and sent is as POST param. Example: {"u":"abc@one-count.com","e":"abc@one-count.com","p":"1234"} OR {"u":"abc@one-count.com","p":"1234"} OR {"e":"abc@one-count.com","p":"1234"} OUTPUT : Should get ocid of the user if it finds it otherwise get and error with msg user not found.

GET method should be used to lookup users.

Request	Type	Description
Lookup params	String	URL encoded key value string parameters for the lookup. Return property has csv of questions id requested back in Users object. Params: Value of question Ids: Key value for Lookup question ids for e.g. 1=user1@email.com return: csv of question id that is requested back. The Users object returned will only have these properties plus UserId (String)

Response	Type	Description
Users	Users	Found users returned with the demo field requested in return parameter in json format.

POST method should be used to create users.

Request	Type	Description
Users	Users	Users object that contains information about user to create. PartnerId Needs to be specified.
Transactions	Transactions	(Array of) transaction object specifying parts of the transaction to be added to the new user. UserId and TransactionId, SubscriptionType will be ignored if specified. As this is new user and new transaction is being added.
DedupeColumns	String	CSV of question id's that should be considered to find duplicate.

Response	Type	Description
Users	Users	Created users returned with the demo field requested in return parameter in json format. If return was not specified only UserId will be returned.

PUT method should be used to update users.

Request	Type	Description
Users	Users	Users object with update fields. Return property has csv of questions id requested back in Users object.
Return	String	CSV of ONEcount QuestionId's requested back in Users object in response
RequestDate	Date	RequestDate to use for the demo update. If not provided current date will be used.

Response	Type	Description
Users	Users	Updated user returned with the demo field requested in return parameter in json format.

Create new users. Here in this example the JSON for request is passed in userFile.json file.
curl -X POST -H "Appkey: xxx" -H "Content-Type: application/json" –data-binary -d '@userFile.json' https://api.onecount.net/v2/users (mailto:@userFile.json)
Products
This resource is for manipulating products resource. A product can be created, updated or searched.

Method	Url	Action
GET	/products	Get all product details
GET	/products/5	Get product id 5
GET	/products/lookup?Title=productname	Lookup products by Title
POST	/products	JSON of the Products type object needs to be sent as post data. Id field should not be sent.
PUT	/products/5	JSON of the Products type object needs to be sent as post data. Id field is mandatory for update.
POST	/products/attachResource	JSON of the Product and Resource ids to be sent as post data. Both fields are mandatory. Example: {"ProductID":"65","ResourceID":"121"}

GET method should be used to lookup products.

Request	Type	Description
Lookup params	String	URL encoded key value string parameter for the lookup. Params: Name: Name of the Product for lookup (String)

Response Type Description

POST method should be used to create products.

Request	Type	Description
Products	Products	Product details in json to be sent as post data. Id should not be set. Example: {"Title":"Test123","Description":Testss","Terms":{"Name":"Product123"},"PrimaryFormId":10,"ResourceID":17}

Response	Type	Description
ProductId	int	Product Id of the newly created product.

PUT method should be used to update an individual product given the product info.

Request	Type	Description
Products	Product	Product details to be updated in json format to be sent with request. Id property needs to be set to identify the product to be updated. If you send term and resource along with product creation then it will automatically attach term to product and resource to product. Possible Request Params: Title, Description, PrimaryFormId, ResourceID Example: {"Title":"Test123","Description":Testss","Terms":{"Name":"Product123"},"PrimaryFormId":10,"ResourceID":17}

Response	Type	Description
ProductId	Int	Product id of the updated product.

Terms
This resource is for manipulating terms resource. A term can be created, updated or searched.

Method	Url	Action
GET	/terms/5	Get term id 5
GET	/terms/lookup?Name=termname	Lookup terms by Name
POST	/terms	JSON of the terms type object needs to be sent as post data. Id field should not be sent.
PUT	/terms/5	JSON of the terms type object needs to be sent as post data. Id field is mandatory for update.

GET method should be used to lookup products.

Request	Type	Description
Lookup params	String	URL encoded key value string parameter for the lookup. Params: Name: Name of the term for lookup (String)

Response	Type	Description
Terms	Terms	Returns found term details.

Request	Type	Description
Terms	Terms	Term details in json to be sent as post data. Id should not be set. Possible Request Params: Name, Description, Duration, DurationUnit, Price, ProductId, Active, ProductStatusId, Quantity, QuantityTxt Example: {"Name":"Test123","Description":Testss","Duration":10,"ProductId":17}

Response	Type	Description
TermId	int	Term Id of the newly created term.

PUT method should be used to update an individual term given the term info.

Request	Type	Description
Terms	Term	Term details to be updated in json format to be sent with request. Id property needs to be set to identify the term to be updated. Example: {"Name":"Test123","Description":Testss","Duration":10,"ProductId":17}

Response	Type	Description
TermId	Int	term id of the updated term.

Resources
This resource is for manipulating resources resource. A resource can be created, updated or searched.

Method	Url	Action
GET	/resources/5	Get resource id 5
GET	/resources/lookup?Name=resourcename	Lookup resources by Name
POST	/resources	JSON of the resources type object needs to be sent as post data. Id field should not be sent.
PUT	/resources/5	JSON of the resources type object needs to be sent as post data. Id field is mandatory for update.

GET method should be used to lookup products.

Request	Type	Description
Lookup params	String	URL encoded key value string parameter for the lookup. Params: Name: Name of the resource for lookup (String)

Response	Type	Description
Resources	Resources	Returns found resource details.

Request	Type	Description
Resources	Resources	resource details in json to be sent as post data. Id should not be set. Possible Request Params: Name, Description, Type, Value Example: {"Name":"Test123","Description":Testss","Type":3,"Value":"/digital/"}

Response	Type	Description
ResourceId	int	Resource Id of the newly created resource.

PUT method should be used to update an individual resource given the resource info.

Request	Type	Description
Resources	Resource	Resource details to be updated in json format to be sent with request. Id property needs to be set to identify the resource to be updated. Example: {"Name":"Test123","Description":Testss","Type":3,"Value":"/digital/"}

Response	Type	Description
ResourceId	Int	resource id of the updated resource.

Sources
This resource is for manipulating sources resource. A source can be created, updated or searched.

Method	Url	Action
GET	/sources/1	Get source id 1.
GET	/sources/lookup?Source=sourcename	Lookup sources by source.
POST	/sources	JSON of the Sources type object needs to be sent as post data. Id field should not be sent.
PUT	/sources	JSON of the Sources type object needs to be sent as post data. Id field is mandatory for update.

Sources can be looked up given the code or Id. GET method should be used for lookup.

Request	Type	Description
Lookup params	String	URL encoded key value string parameter for the lookup. Params: Source: Source value (String)

Response	Type	Description
Sources	Sources	Returns found source details.

POST method should be used to create an individual source given the source parameters.

Request	Type	Description
Sources	Sources	Defines the contents that makes up the source. Id parameters should not be set.

Response	Type	Description
SourceId	int	Returns created source code id.

PUT method can be used to update an individual source given the id.

Request	Type	Description
Sources	Sources	Defines the contents that makes up the source. The id parameter needs to be set which will identify the id of the source to be updated.

Response	Type	Description
SourceId	int	Returns updated source id.

Transactions
This resource is for manipulating transactions resource. A transaction can be created or searched.

Method	Url	Action
GET	/transactions	List all transactions
GET	/transactions/lookup?UserId=1	Lookup all transaction of UserId = 1
POST	/transactions	JSON of the Transactions type object needs to be sent as post data. Id field should not be sent.

Transactions can be looked up using transactionId, date range, userid. Use GET method to do lookup.

Request	Type	Description
Lookup params	String	URL encoded key value string parameter for the lookup. Params: UserId: Id of the user whose transaction is to be looked up (Int) StartDate: Date from which the start should happen. Only valid when UserId is set. (Date) EndDate: When the search should end. Only valid when UserId is set. (Date)

Response	Type	Description
Transactions	Transactions	Returns all transaction that satisfies the search criteria.

POST method can be used to create user transaction. Transaction info needs to be sent as request and a TransactionId will be returned when thetransaction is created.

Request	Type	Description
Transactions	Transactions	Contains fields that define a transaction. Id field should not be set.

Response	Type	Description
TransactionId	int	Returns transactionId of the newly created transaction.

Stats
Stats resource can be used to submit any type of stat collected on the third party systems. Each type of stat will be represented by a
sub-resource. So, for telemarketing it could be /stats/telemarketing endpoint, for videos it can be /stats/videos, for webinar it could be /stats/we binars etc. Right now we only have telemarketing sub-resource.

Telemarketing

This resource is for manipulating telemarketing stat resource. A telemarketing stat can be created or listed.

Method	Url	Action
GET	/stats/telemarketing	List telemarketing stats
GET	/stats/telemarketing/1000	Get telemarketing stat whose id is 1000 in the system.
POST	/stats/telemarketing	JSON of the Telemarketing type object needs to be sent as post data. Id field should not be sent.

POST method can be used to create telemarketing stat. Telemarketing info needs to be sent as request and an Id will be returned when the transaction is created.
Request Type Description

Telemarketing	Telemarketing	Contains fields that define a telemarketing stat. Id field should not be set. Refer to telemarketing object in references section.
			Workflow: OCID: This id is required field. This represents the unique id of the user in onecount system. This id can be looked up from the /user/lookup resource if the ocid is not known by providing user demographic questions, if not found new user needs to be created in the onecount system by posting the user demographic from /user resource. If the ocid is found send the demo data to user resource (PUT) to update the demographic information.
			E.g
			{
<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="cd8549bf-7710-433a-9bfa-2d563e29983f"><ac:plain-text-body><![CDATA[				"Telemarketing":[	]]></ac:plain-text-body></ac:structured-macro>
			{
			"OCID":"5000",
			"Date": "2016-01-01",
			"Time": "10:10:10",
			"ResourceId":"250",
			"PageUrl": "http://www.one-count.com/detail/a.php",
			"PageTitle":"tests"
			}
			]
			}

Response	Type	Description
Ids	String	Returns telemarketing ids of the newly created transaction. If multiple stats are sent, multiple ids are returned in cvs format.

Reference
Type: Questions

Property Name	Type	Description
Id	Int	Id of the question.
Text	String	Text of the question.
Type	Int	Determines which type of question it is. Textbox, checkbox, select, radio. There can be 6 types of questions. type=1 means textbox type questions or short response type question. The response length needs to be less than 255 characters. type=2 means textarea type question or long response type question. type=3 means password type question. This is basically same as type 1 but when displayed in ONEcount frontend forms typed characters appears as * type = 4 means select or dropdown type questions. This is a multiple choice, 1 response type question. When creating this type of question the choices block also needs to be part of the questions object that will hold the possible choices of the select question. type=5 means radio button type question. This is a multiple choice, 1 response type question. When creating this type of question the choices block also needs to be part of the questions object that will hold the possible choices of the radio question. type=6 means checkbox type question. This is a multiple choice, multi response type question. When creating this type of question the choices block also needs to be part of the questions object that will hold the possible choices of the checkbox question.
Choices	choices	If multiple choice question this field will have the choices.
Alias	String	Alias for admin purpose.

Type: Choices

Property Name	Type	Description
Id	int	Id of the choice.
Text	string	Display text of choice.
Value	String	Value stored in db.
Order	Int	Display order.
QuestionId	Int	Tied to which question id.

Type: Users

Property Name	Type	Description
Id	Int	ID of the user in ONEcount.
PartnerId	Int	ID of the user in partners system (e.g. id of your system).
Demo	Demo	Object of user's demo question ids and respective response values.
RequestDate	Date	Request date.

Type: Demo

Property Name	Type	Description
QuestionId (e.g 6)	String	6 is the value of "Id" property of question resource(Text = "First Name")
QuestionId (e.g 7)	String	7 is the value of "Id" property of question resource(Text = "Last Name")
...	...	...

Type: Transactions

Property Name	Type	Description
Id	Int	ID of the transaction.
UserId	Int	Id of user in ONEcount.
TermId	Int	TermId in ONEcount.
ProductStatus	Int	Status ID.
SubscriptionType	Char	Can be n,r or u for new, renew or unsubscribe.
TransactionDate	Date	Date when the transaction occurred.
TransactionTime	Time	Time of transaction.
RequestDate	Date	The effective request date for the transaction.
UserIP	String	IP of the user.
Source	String	The transaction needs to be tied to a source code this will define it.
MediaFilePath	String	The url of media associated with that transaction. Eg image, audio.

ExpireDate	Date	Date when the subscription expires.
Amount	Float	If there is amount (USD) included in transaction.

Type: Sources

Property Name	Type	Description
Id	Int	Id of the source.
Source	String	Value of the source.
Description	Text	Description of the source.
ParentId	int	If this is a child source then list the parent source id.

Type: Products

Property Name	Type	Description
Id	Int	Specify only for update.
Name	String	Name of the Product.
Description	Text	Description of the product.
Terms	Terms	(Array of) Terms associated with the product.

Type: Terms

Property Name	Type	Description
Id	int	Id of the term.
Name	string	Name of the Term.
Description	text	Description of the term.
Duration	int	Duration of term validity.
DurationUnit	sting	Y (year), M (Month), D (Days).
ProductId	int	Id of the product the term is tied to.
Price	float	If there is price (USD) for the term.

Type: Resources

Property Name	Type	Description
Id	Int	Specify only for update.
Name	String	Name of the Resource.
Description	Text	Description of the Resource.

Type	Int	Type Options 0 : File 2 : Newsletter 3 : Section 4 : Page 5 : Function
Value	String	Value of Resource Type. Example : if the Type sent is 3 then Value would be /digital/ For Function type resource it can be blank.

Type: Telemarketing

Property Name	Type	Description
Id	int	Id of the telemarketing stat. This is autogenerated from the system and can be used to lookup the stat.
OCID	int	Onecount ID of the user.
Date	Date	Date when the stat occurred. Format: yyyy-mm-dd
Time	Time	Time of stat. Format: h:m:s (24 hour format)
ResourceId	int	Id of resource currently being sent for the sat. If the resource type is page type resource then need to send PageTitle otherwise it will follow the process described in PageTitle.
PageUrl	string	Page Url belongs to resource that is being sent with this request. If the resource is file type then it needs to be path to that file and if the resource is section it needs to be section. Basically the value here needs to exact what is defined while creating resource.
PageTitle	string	Page title that belongs to the page url that is being sent. If not provided it try to pull the title from the page but if unsuccessful then it will set it as blank. If the page url already exists and it doesn't match with the one that is being sent then it will throw conflict error with the title in our system.