Version 1.0C

Introduction

With MobiWeb SMS Coupons API you can generate, send and redeem mobile coupons for your mobile applications, websites, services and businesses.

The SMS Coupons API is based on REST. It uses built-in HTTP authentication and HTTP status codes. All data exchange is done in JSON format.

To test the SMS Coupons API, you will need a valid API account. If you don't have one yet, click here to register for a FREE account.

Authentication

https://[HOST]/apis/auth

SMS Coupons

https://[HOST]/apis/coupon/v1/

Coupon Redemption

https://[HOST]/coupon/apis/v1/redeem/

[HOST]

Replace [HOST] with your API account domain name or IP.

Authentication

Each request must be accompanied by a valid access_token. access_token are generated upon successful authentication. To authenticate you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value access_token , username and password.

access_token

If the request succeeded, an authentication object is returned, which includes an access_token and a refresh_token. Otherwise, an error is returned. access_token grants you access to make requests.

Setup the Authorization HTTP header with your access_token. Authorization: Bearer dcec4eb6-035c-41a4-9871-82c5bd3ef379

access_token is valid for 30 minutes, after which it expires. To preserve connection you must either refresh with refresh_token or reset connection and request a new access_token.

refresh_token

To refresh connection you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value "refresh_token" , refresh_token with value the refresh token, provided by a previously successful auth request.

Authentication

POST https://[HOST]/apis/auth
POST https://[HOST]/apis/auth
Content-Type : application/json
{
	 "type" : "access_token",
	 "username" : "myusername",
	 "password" : "mypassword"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
	 }
}

Refresh Connection

POST https://[HOST]/apis/auth
Content-Type : application/json
{
	 "type" : "refresh_token",
	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641",
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "0e3f6ecb-7a7e-4d03-a004-d710db8978ab",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "ecbb4d30-6da2-4b78-998e-d01025c648f2"
	 }
}

Send Coupon

To send a coupon you must first create a campaign. To create a campaign you must send a campaigns POST request.

https://[host]/apis/coupon/v1/campaigns

This request accepts parameters name, the campaign name and brand, the brand name that will appear in the coupon links of your campaign. Optional parameters are expiration_date, the campaign time of expiration and template_id, the template that will be shown to the user when he/she opens the link.

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned with a campaignid.

Send Text Coupon With Your Code

To send a coupon you must send a single_coupon request.

https://[host]/apis/coupon/v1/single_coupon

Set parameters campaign_id with the id of a valid campaign, coupon_type with value "text", coupon_text_type with value "simple_text" and phone with the recipient phone number of the SMS coupon in E.164 format.

Setup coupon object with attribute source : "select" and config object attribute code with you coupon code.

Finally, setup sms object attribute text with your message text and attribute originator with your preffered sender.

Remember to put placeholder [CODE] in sms object attribute text, in the position you prefer your coupon code to appear.

If the request succeeded, a response object is returned, which includes id, redemption_api_key for redeeming coupon codes, broadcast_date, expiration_date and the cost of the coupon. Otherwise, an error is returned.

Send Text Coupon With Generated Code

To send a coupon you must send a single_coupon request.

https://[host]/apis/coupon/v1/single_coupon

Set parameters campaign_id with the id of a valid campaign, coupon_type with value "text", coupon_text_type with value "simple_text" and phone with the recipient phone number of the SMS coupon in E.164 format.

Setup coupon object with attribute source : "generate", config object attribute coupon_digits with value 20 and object attribute code_type with value "numeric".

coupon_digits indicates the length of the generated coupon code and code_type indicates the the format of the generated coupon code.

Finally, setup sms object attribute text with your message text and attribute originator with your preffered sender.

Remember to put placeholder [CODE] in sms object attribute text, in the position you prefer your coupon code to appear.

If the request succeeded, a response object is returned, which includes id, the generated code, redemption_api_key for redeeming coupon codes, broadcast_date, expiration_date and the cost of the coupon. Otherwise, an error is returned.

Send Generated QR Coupon With Template

To send a coupon you must send a single_coupon request.

https://[host]/apis/coupon/v1/single_coupon

Set parameters campaign_id with the id of a valid campaign, coupon_type with value "qr_code", template_id with the id of a valid campaign and phone with the recipient phone number of the SMS coupon in E.164 format.

Setup coupon object with attribute source : "generate", config object attribute coupon_digits with value 20 and object attribute code_type with value "numeric".

coupon_digits indicates the length of the generated coupon code and code_type indicates the the format of the generated coupon code. Templates are mobile web pages that are displayed when a user clicks a coupon link. You can create and customize reusable templates through our web portal. Setting coupon_type with value "qr_code" will cause the API to create a QR coupon with the generated code automatically.

Finally, setup sms object attribute text with your message text and attribute originator with your preffered sender.

Remember to put placeholder [LINK] in sms object attribute text, in the position you prefer your coupon link to appear.

If the request succeeded, a response object is returned, which includes id, the generated code, redemption_api_key for redeeming coupon codes, broadcast_date, expiration_date and the cost of the coupon. Otherwise, an error is returned.

Send Text Coupon With Your Code

POST https://[host]/apis/coupon/v1/campaigns
POST https://[HOST]/apis/coupon/v1/campaigns
Content-Type : application/json
{
	 "name" : "Discount Campaign #1",
	 "brand" : "ecommerce-discounts"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 12353
	 }
}
POST https://[host]/apis/coupon/v1/single_coupon
POST https://[HOST]/apis/coupon/v1/single_coupon
Content-Type : application/json
{
	 "campaign_id" : 12353,
	 "phone" : "447546756743",
	 "coupon_type" : "text",
	 "coupon_text_type" : "simple_text"
	 "coupons" : {
		 "source" : "select",
		 "config" : {
			 "code" : "DG32KJHK32JK32J"
		 }
	 },
	 "sms" : {
		 "text" : "Here is your discount code: [CODE]"
		 "originator" : "Discount"
	 }
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 221276323,
	 	 "redemption_api_key" : das9dj320ej39rj29rj3b4htlk54324
	 	 243djasd3232r4tu5u,
	 	 "broadcast_date" : "2015-11-23 14:34:20",
	 	 "expiration_date" : "",
	 	 "cost" : "0.0500"
	 }
}

Send Text Coupon With Generated Code

POST https://[host]/apis/coupon/v1/single_coupon
POST https://[HOST]/apis/coupon/v1/single_coupon
Content-Type : application/json
{
	 "campaign_id" : 12353,
	 "phone" : "447546756743",
	 "coupon_type" : "text",
	 "coupon_text_type" : "simple_text"
	 "coupons" : {
		 "source" : "generate",
		 "config" : {
			 "coupon_digits" : 20,
			 "code_type" : "numeric"
		 }
	 },
	 "sms" : {
		 "text" : "Here is your discount code: [CODE]"
		 "originator" : "Discount"
	 }
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 5641276323,
	 	 "redemption_api_key" : das9dj320ej39rj29rj3b4htlk54324
	 	 243djasd3232r4tu5u,
	 	 "code" : "32209482390423408954",
	 	 "broadcast_date" : "2015-11-20 22:34:46",
	 	 "expiration_date" : "",
	 	 "cost" : "0.0250"
	 }
}

Send Generated QR Coupon With Template

POST https://[host]/apis/coupon/v1/single_coupon
POST https://[HOST]/apis/coupon/v1/single_coupon
Content-Type : application/json
{
	 "campaign_id" : 12353,
	 "phone" : "447546752133",
	 "coupon_type" : "qr_code",
	 "template_id" : 43
	 "coupons" : {
		 "source" : "generate",
		 "config" : {
			 "coupon_digits" : 20,
			 "code_type" : "numeric"
		 }
	 },
	 "sms" : {
		 "text" : "Here is your discount code: [LINK]"
		 "originator" : "Discount"
	 }
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 56422276543,
	 	 "redemption_api_key" : das9dj320ej39rj29rj3b4htlk54324
	 	 243djasd3232r4tu5u,
	 	 "code" : "32209482323453408954",
	 	 "broadcast_date" : "2015-11-01 20:14:16",
	 	 "expiration_date" : "",
	 	 "cost" : "0.0300"
	 }
}

Redeem Coupon

To redeem a coupon you must send a redeem POST request.

https://coupon/apis/v1/redeem/{redemption_api_key}/{code}

Replace {redemption_api_key} with the api key provided by your single_coupon or broadcast request and {code} with the coupon code.

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned with the result of the redemption attempt.

Redeem Code

POST https://coupon/apis/v1/redeem/{redemption_api_key}/{code}
POST https://coupon/apis/v1/redeem/{das9dj320ej39rj29rj3b4htlk54324243djasd3232r4tu5u}/{DFE7879632213TYWW435345}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 }
}

Contact Catalogs

Get Catalogs

Catalogs are useful for managing your contacts. To get your catalogs you must send a catalogs GET request.

https://[host]/apis/coupon/v1/catalogs

If the request succeeded, a response object with an array of existing catalogs is returned. Catalog objects have attributes catalog id, catalog name and total_contacts of the catalog. Otherwise, an error is returned.

Create A Catalog

To create a catalog for your contacts you must send a catalogs POST request.

https://[host]/apis/coupon/v1/catalogs

Set parameter name with the desired name of your catalog. If you wish to upload contacts to your catalog, setup optional parameter file with a valid file reference returned from a successful upload request.

If the request succeeded, a response object with the catalog id is returned. Otherwise, an error is returned.

Delete A Catalog

To delete a catalog and it's contacts you must send a catalogs DELETE request.

https://[host]/apis/coupon/v1/catalogs/{id}

Replace {id} with the id of the catalog.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Get Catalog Contacts

To get contacts of a catalog you must send a contacts GET request.

https://[host]/apis/coupon/v1/catalogs/{id}/contacts

Replace {id} with the id of the catalog.

If the request succeeded, a response object with an array of contacts is returned. Contact objects have attributes id, fullname and phone. Otherwise, an error is returned.

Add Contact To Catalog

To add a contact in a catalog you must send a contacts POST request.

https://[host]/apis/coupon/v1/catalogs/{id}/contacts

Set parameter name with the fullname of the contact and phone with the mobile number of the contact in E.164 format.

If the request succeeded, a response object with the contact id is returned. Otherwise, an error is returned.

Delete A Contact

To delete a contact you must send a contacts DELETE request.

https://[host]/apis/coupon/v1/catalogs/{id}/contacts/{cid}

Replace {id} with the id of the current contact's catalog.

Replace {cid} with the id of the contact.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Move Contact Between Catalogs

To move a contact between 2 catalogs you must send a move POST request.

https://[host]/apis/coupon/v1/catalogs/{id}/contacts/move

Replace {id} with the id of the contact's catalog.

Set parameter target_catalog_id with the target catalog id and contact_id with the id of the contact.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Get Catalogs

GET https://[host]/apis/coupon/v1/catalogs
GET https://[HOST]/apis/coupon/v1/catalogs
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "catalogs" : [
	 	 	{
	 	 		 "id" : 11345,
	 	 		 "name" : "Catalog #4",
	 	 		 "total_contacts" : 345032
	 	 	},
	 	 	{
	 	 		 "id" : 11346,
	 	 		 "name" : "Catalog #5",
	 	 		 "total_contacts" : 3495
	 	 	}
	 	 ],
	 	 "total_catalogs" : 2
	 }
}

Create A Catalog

POST https://[host]/apis/coupon/v1/catalogs
POST https://[HOST]/apis/coupon/v1/catalogs
Content-Type : application/json
{
	 "name" : "Catalog #1"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 362201
	 }
}

Delete A Catalog

DELETE https://[host]/apis/coupon/v1/catalogs/{id}
DELETE https://[HOST]/apis/coupon/v1/catalogs/34871
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Get Catalog Contacts

GET https://[host]/apis/coupon/v1/catalogs/{id}/contacts
GET https://[HOST]/apis/coupon/v1/catalogs/1978/contacts
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "contacts" : [
	 	 	{
	 	 		 "id" : 12380192332,
	 	 		 "fullname" : "Nick Tiri",
	 	 		 "phone" : "447546756743"
	 	 	},
	 	 	{
	 	 		 "id" : 112898922346,
	 	 		 "fullname" : "Mark Derk",
	 	 		 "phone" : "447546233741"
	 	 	}
	 	 ],
	 	 "total_contacts" : 2
	 }
}

Add Contact To Catalog

POST https://[host]/apis/coupon/v1/catalogs/{id}/contacts
POST https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts
Content-Type : application/json
{
	 "name" : "Mark Josh",
	 "phone" : "447546233741"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 46732145
	 }
}

Delete A Contact

DELETE https://[host]/apis/coupon/v1/catalogs/{id}/contacts/{cid}
DELETE https://[HOST]/apis/coupon/v1/catalogs/34871/contacts/46732145
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Move Contact Between Catalogs

POST https://[host]/apis/coupon/v1/catalogs/{id}/contacts/move
POST https://[host]/apis/coupon/v1/catalogs/34871/contacts/move
Content-Type : application/json
{
	 "target_catalog_id" : 65742,
	 "contact_id" : 245345347
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Coupon Groups

Get Groups

Catalogs are useful for managing your coupons. To get your groups you must send a groups GET request.

https://[host]/apis/coupon/v1/groups

If the request succeeded, a response object with an array of existing groups is returned. Group objects have attributes catalog id, group name, type of coupons that are stored in the group ( each group has only one type of coupons ) and total_codes of the group. Otherwise, an error is returned.

Create A Group

Groups are useful for managing your coupons. To create a group for your coupons you must send a groups POST request.

https://[host]/apis/coupon/v1/groups

Set parameter name with the desired name of your group and parameter type with the type of coupons that you will store in the group ( e.g. "qr_code").

If the request succeeded, a response object with the catalog id is returned. Otherwise, an error is returned.

Delete A Group

To delete a group and it's coupons you must send a groups DELETE request.

https://[host]/apis/coupon/v1/groups/{id}

Replace {id} with the id of the group.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Get Group Coupons

To get contacts of a group you must send a coupons GET request.

https://[host]/apis/coupon/v1/groups/{id}/coupons

Replace {id} with the id of the group.

If the request succeeded, a response object with an array of coupons is returned. Coupon objects have attributes id, coupon code and type of coupon ( "qr_code" etc. ). Otherwise, an error is returned.

Add Coupon To Group

To add a coupon in a group you must send a groups POST request.

https://[host]/apis/coupon/v1/groups/{id}/coupons

Set parameter code with the coupon code. Set optional parameter svg in the coupon group type is for images.

If the request succeeded, a response object with the coupon id is returned. Otherwise, an error is returned.

Delete A Coupon

To delete a coupon you must send a coupons DELETE request.

https://[host]/apis/coupon/v1/groups/{id}/coupons/{cid}

Replace {id} with the id of the current coupon's group.

Replace {cid} with the id of the coupon.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Move Coupon Between Groups

To move a coupon between 2 groups you must send a move POST request.

https://[host]/apis/coupon/v1/groups/{id}/coupons/move

Replace {id} with the id of the coupon's group.

Set parameter target_group_id with the target group id and coupon_id with the id of the coupon.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Get Groups

GET https://[host]/apis/coupon/v1/groups
GET https://[HOST]/apis/coupon/v1/groups
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "groups" : [
	 	 	{
	 	 		 "id" : 11500,
	 	 		 "name" : "Group #1",
	 	 		"type" : "2dbarcode_aztec",
	 	 		 "total_coupons" : 345
	 	 	},
	 	 	{
	 	 		 "id" : 11501,
	 	 		 "name" : "Group #2",
	 	 		"type" : "2dbarcode_datamatrix",
	 	 		 "total_coupons" : 2
	 	 	},
	 	 	{
	 	 		 "id" : 11502,
	 	 		 "name" : "Group #3",
	 	 		"type" : "2dbarcode_pdf417",
	 	 		 "total_coupons" : 12
	 	 	},
	 	 	{
	 	 		 "id" : 11503,
	 	 		 "name" : "Group #4",
	 	 		"type" : "qr_code",
	 	 		 "total_coupons" : 2
	 	 	}
	 	 ],
	 	 "total_groups" : 4
	 }
}

Create A Group

POST https://[host]/apis/coupon/v1/groups
POST https://[HOST]/apis/coupon/v1/groups
Content-Type : application/json
{
	 "name" : "Group #1",
	 "type" : "qr_code"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 11450
	 }
}

Delete A Group

DELETE https://[host]/apis/coupon/v1/groups/{id}
DELETE https://[HOST]/apis/coupon/v1/groups/11502
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Get Group Coupons

GET https://[host]/apis/coupon/v1/groups/{id}/coupons
GET https://[HOST]/apis/coupon/v1/groups/11503/coupons
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "coupons" : [
	 	 	{
	 	 		 "id" : 546452211,
	 	 		 "code" : "fa2881sn100",
	 	 		 "type" : "qr_code"
	 	 	},
	 	 	{
	 	 		 "id" : 546452212,
	 	 		 "code" : "fa2881sn101",
	 	 		 "type" : "qr_code"
	 	 	}
	 	 ],
	 	 "total_coupons" : 2
	 }
}

Add Coupon To Group

POST https://[host]/apis/coupon/v1/groups/{id}/coupons
POST https://[HOST]/apis/coupon/v1/groups/11503/coupons
Content-Type : application/json
{
	 "code" : "HD833B30FDVV587KSDFUHE4"
	}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 1801108008
	 }
}

Delete A Coupon

DELETE https://[host]/apis/coupon/v1/groups/{id}/coupons/{cid}
DELETE https://[HOST]/apis/coupon/v1/groups/11503/coupons/1801108008
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Move Coupon Between Groups

POST https://[host]/apis/coupon/v1/groups/{id}/coupons/move
POST https://[host]/apis/coupon/v1/groups/11300/coupons/move
Content-Type : application/json
{
	 "target_group_id" : 12400,
	 "coupon_id" : 3300451123
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Files Management

Upload A File

Files are useful for uploading contacts, coupon codes and images of coupons and passbooks. To upload a file you must send a upload POST request.

https://[host]/apis/coupon/v1/upload

Content-Type: multipart/form-data

Set parameter owner_type with the owner type of your file ( e.g. value "group"), parameter file with the file that you will upload ( e.g. value "group.xlsx") and parameter group_code_column with the column position of the coupon codes in the file ( e.g. value "left").

If the request succeeded, a response object with the file_reference is returned. The file is temporarily stored for future use. file_reference expires after 30 minutes and the file is deleted. Use it with a create catalog / group / passbook command to store file data. Otherwise, an error is returned.

Download A File

You can download passbook images. To download a file you must send a download POST request.

https://[host]/apis/coupon/v1/download/{reference}

Replace {reference} with a valid reference of an image returned by a successful passbooks GET request.

If the request succeeded, an image file is returned. Otherwise, an error is returned.

Upload A File

POST https://[host]/apis/coupon/v1/upload
POST https://[HOST]/apis/coupon/v1/upload
Content-Type : multipart/form-data
{
	 "file" : "groups.xlsx",
	 "owner_type" : "group"
	 "group_code_column" : "left"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "file_reference" : "ca1cfb80b50b411033aa30ea2199af25"
	 }
}

Download A File

GET https://[host]/apis/coupon/v1/download/{reference}
GET https://[HOST]/apis/coupon/v1/download/8DDH4K234JF0EWFF03HFFH0FH3
Content-Type : image/jpeg
				!	1
A"v∂w∑89Qatµ67xq2#≥4÷óÅë±BR3s$UW°r“ìTï’ñX—b≤S%5uV'◊ò∏Çí¢Cg¬cîG(!1AQaq"6Åë±2r≤s≥tu°B¬#3457¡Rbí“$T¥—ÇSÉìU¢Cî‘%”„eV·£√D&‚cd§'ˇ⁄?ø¿" " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " "¯û}àÕ©È4√I˝ÛØ8ÜõO_Gyk4§ø∂?Mcfir∞Ô_ó9¨ú@5‚-6¶±§'NÁb‡µ^	∫V9m5#ªÈ%"Dˆ‘J˚›:åµæfi◊ÓÈÙ[π+”,2;‹jƒ‹Ó»y}gsÕiÌ∏/	îx±ºã笋∫˙EÃÁÃHç‰p;≤Zªç∞‹µ8Pî˚´>âGâfiQüB#1óó`oX-.óz€V
óùÄëL‘¶î	"Ï;ãÊi∞Í˙{Ø^h÷	ŸW¿
hIÏ©ÏY‹js@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D
@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@DP’»O0
õb‰∏ñõB#°
Öcão3-'≥:LGg^=‘»êÂ-5+&^‚ p∫˝√låg-∏u»ÔÔw6∑·ΩÁ⁄lt˚´sÎ
≥co˜;]Jw|ì#‹í7‹™∆ñ~h—M¶èH€ù:0ıÊiY≤?pfièYSfæÔfiKùFvWÈ*
fi≠^—'ÿ/{=≈Ø\z«¬AZ4˘ª≥∆—ÏÜ6CÌç¨<Õˆ„∆¥’k-u^ì#$9:◊%∂Z:óbç∂
ô+2˚ù‚!ùáÅ6€hn/Ôû|
dL˚ß?∏∞˙ƒÓáí-¥À«Ö“À'‹è›X÷€Ãìñ5Aπ¡®[22Î∞¥KRL˝“v‚÷√©óflOAù∂·}Ö§±]Ã|.ûüqåo∫µ˚Æs‰i›X$∞Åæ€ómÚª‹X÷Áó|õº5ù…ë¡Ô(‘i°Ø∆Ë—€◊±>£Jáûfi¬%vıØÏ+O…Èp?Â,üÙ˚ã_ªÂ.Gº¸¶Ø<%˚ë˜V:∏‹ªó!A5}∑∂m´e◊£oÊ∑¨6]‚Ë}÷†ÃàŸu˝¡ö∂⁄˚^»Ê≥”l#wä…ˆ‹◊Å∫›õ∫˘πoumJAıâ˜#,”ÍŒHnM7yÔÃÚ+ ∏Ú˝æì]ÿfi–dP…I9PÕ“&?SbÛ)4±.2€[Nt5í—fiA¯7∆€¢—÷ó÷∞Cp·FOméHùÿ|¿–ˆÉÔò‡A°i°^̪ø˜~“ªeÓùysql◊VKiÂ|±Ã‹34ù»cÿÊÂu36≠65¡s
çÉÜ‚˘≈
‘∫|≤ä≤˙øƒÈ‚¢=îF•%á…&i)Õ√m¬#2%§»R
[Lπ—µ;ç&RÍfigFÔZH®Ò£ƒU¯—ı[MsJ∂÷,MlÓ†d¨=π^–·_≠çz°èY$@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@DZ;¥y˘¶5ñaë`™¨Õrª¸Zi’›9èU@M4kV⁄Cí´ikk^R%¿SÑá¸6÷€nuG|‘ïK;á7Nø¶A´â-m¨Óùù„›ú≤¥»∆:çu*⁄êH∆î òwqÛv–€∫µ∆àËÔ.Ø≠_íNÍ6˜aÙ≥;fi¿Á6†;-COöN`@¿÷^h’‚"óI‰/´©ì/\eÙµÌü¯*q™¯VÓvó∏G˝ë∏A͡sÅ∫’`¥2}∑9ÅiS˙«Ÿ‚,Ùk¢{ìD¡ˇsº+Y˘ùm7ú_¿∫≥Øhˇ≈ù•ÓClÍ~˙—=:xî_∫3∂¸∑ö—Ù≠BÒÓ˛Ñq∞}“ıØ‹˙≈nG∏˝K±c;ÊïÁ⁄llumg
				
				
				
				
			

Templates

Get Templates

Templates are mobile web pages that are displayed when a user clicks a coupon link with your coupons. To get your templates you must send a templates GET request.

https://[host]/apis/coupon/v1/templates

If the request succeeded, a response object with an array of existing templates is returned. Template objects have attributes template id, template name and create_date of the template. Otherwise, an error is returned.

Get Templates

GET https://[host]/apis/coupon/v1/templates
GET https://[HOST]/apis/coupon/v1/templates
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "templates" : [
	 	 	{
	 	 		 "id" : 2500,
	 	 		 "name" : "Airline",
	 	 		"create_date" : "2015-02-13 11:08:42",
	 	 	},
	 	 	{
	 	 		 "id" : 2501,
	 	 		 "name" : "Retail",
	 	 		"create_date" : "2015-02-13 22:23:18",
	 	 	},
	 	 	{
	 	 		 "id" : 2535,
	 	 		 "name" : "E-Shop",
	 	 		"create_date" : "2015-04-22 08:05:22",
	 	 	}
	 	 ],
	 	 "total_templates" : 3
	 }
}

Campaigns

Get Campaign

Sent coupons belong to a campaign. To get a campaign you must send a campaigns GET request.

https://[host]/apis/coupon/v1/campaigns/{id}?offset={offset}&limit={limit}

Replace {id} with the id of the campaign.

Replace {offset} with the target offset of coupons you want the request to return in the response.

Replace {limit} with the target limit of coupons you want the request to return in the response.

If the request succeeded, a response object with campaign information and an array of coupon objects are returned. Campaing information contains attributes campaign id, campaign name, group_id and group_name of coupon group used for this campaign, campaign broadcast_date, campaign expiration_date, total_coupons of campaign, number of coupons_opened, number of coupons_redeemed and the total_cost of the campaign.

Coupon objects have attributes code_id, coupon code, contact phone, coupon status, coupon type, coupon cost, coupon redemption_mode, coupon max_repetitions, coupon current repetitions, text message, create_date, open_date and redeemed_dates. Otherwise, an error is returned.

Create A Campaign

To create a campaign you must send a campaigns POST request.

https://[host]/apis/coupon/v1/campaigns

This request accepts parameters name, the campaign name and brand, the brand name that will appear in the coupon links of your campaign. Optional parameters are expiration_date, the campaign time of expiration and template_id, the template that will be shown to the user when he/she opens the link.

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned with a campaignid.

Get Campaign

GET https://[host]/apis/coupon/v1/campaigns/{id}?offset={offset}&limit={limit}
GET https://[HOST]/apis/coupon/v1/campaigns/34041?offset=10000&limit=1
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "campaign" : {
			 "id" : 543302,
			 "name" : "Music Concert Campaign 08-2015",
			 "group_id" : 12002,
			 "group_name" : "Music Concert Tickets",
			 "broadcast_date" : "2014-03-15 10:00:00",
			 "expiration_date" : "2014-04-15 10:00:00",
			 "total_coupons" : 155237,
			 "coupons_opened" : 131201,
			 "coupons_redeemed" : 96022,
			 "total_cost" : "7761.8500"
		 },
		 "coupons" : [
			{
				 "code_id" : 450032,
				 "code" : "DH876YTR456BVCN79763DS",
				 "phone" : "447546752133",
				 "status" : "redeemed",
				 "type" : "qr_code",
				 "cost" : "0.0500",
				 "redemption_mode" : "http-api",
				 "max_repetitions" : 1,
				 "repetitions" : 1,
				 "message" : "Click the link to open your concert
				 ticket: http://[HOST]/coupon/music/DH876YTR456BVC
				 N79763DS",
				 "create_date" : "2015-10-22 15:00:00",
				 "open_date" : "2015-10-22 15:05:22",
				 "redeemed_dates" : "2015-10-28 08:22:10"
		 	}
		 ]
	 }
}

Create A Campaign

POST https://[host]/apis/coupon/v1/campaigns
POST https://[HOST]/apis/coupon/v1/campaigns
Content-Type : application/json
{
	 "name" : "Discount Campaign #1",
	 "brand" : "ecommerce-discounts"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 12353
	 }
}

Passbooks

Create A Passbook

Coupons support passbook for iOS devices, extending functionality of coupons with location and time based notifications. To create a passbook ( e.g. event ticket ) you must send a passbooks POST request.

https://[host]/apis/coupon/v1/passbooks

Set parameter type with value "event_ticket" and object images attributes icon / logo / thumbnail with valid file_references of uploaded images respectively.

Next setup passbook visible information Header fields, Primary fields, Secondary fields, Auxiliary fields and Back fields.

Each field type is shown in a seperate position of the passbook, depending on the type of passbook. Define fields by setting the appropriate objects array with attributes key, label and value.

keys must be unique.

Finally setup object general attribute description with your event description and attribute logo_text with the text you want to appear in the header, beside your logo image.

SMS Coupons API supports multiple passbook types. Please check the corresponding passbook requests reference for a complete list.

If the request succeeded, a response object with the passbook id is returned. Otherwise, an error is returned.

Get A Passbook

To get a campaign you must send a passbooks GET request.

https://[host]/apis/coupon/v1/passbooks/{id}

Replace {id} with the id of the passbook.

If the request succeeded, a passbook object is returned. Passbook object has attributes passbook type, object general with description and logo_text, object images with retina and non retina download urls of icon, logo and thumbnail images, object fields with arrays of keys / labels / values for header, primary, secondary, auxiliary and back fields. If location notifications are set for the passbook an array of location objects with attributes place name, latitude, longitude is returned, If date notifications are set, notification date is returned. Otherwise, an error is returned.

Delete A Passbook

To delete a passbook you must send a passbooks DELETE request.

https://[host]/apis/coupon/v1/passbooks{id}

Replace {id} with the id of the passbook.

If the request succeeded, a response object with http status code 200 is returned. Otherwise, an error is returned.

Create A Passbook

POST https://[host]/apis/coupon/v1/passbooks
POST https://[HOST]/apis/coupon/v1/passbooks
Content-Type : application/json
{
	 "type" : "event_ticket",
	 "images" : {
	 	 "icon" : "ca1cfb8cb12b411033aa30ea2199af25",
	 	 "logo" : "ca1cfbc0b12b411093ab30ea2199cb78",
	 	 "thumbnail" : "ca1cfb81b12b41103300fcea2199af02"
	 },
	 "fields" : {
	 	 "header" : [
		 	 {
		 		 "key" : "HCE",
		 		 "label" : "Event",
		 		 "value" : "BC"
		 	 }
		 ],
	 	 "primary" : [
		 	 {
		 		 "key" : "HETNM",
		 		 "label" : "Event name",
		 		 "value" : "Music Concert"
		 	 }
		 ],
	 	 "secondary" : [
		 	 {
		 		 "key" : "HCEATND",
		 		 "label" : "Attendee",
		 		 "value" : "John Smith"
		 	 }
		 ],
	 	 "auxiliary" : [
		 	 {
		 		 "key" : "HCELOC",
		 		 "label" : "Location",
		 		 "value" : "London, UK"
		 	 }
		 ],
	 	 "back" : [
		 	 {
		 		 "key" : "DESC",
		 		 "label" : "Description",
		 		 "value" : "Music Concert in London"
		 	 }
		 ]
	 },
	 "general" : {
	 	 "description" : "Music Concert Ticket",
	 	 "logo_text" : "Band Concert"
	 }
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
		 "id" : 88432496872
	 }
}

Get A Passbook

GET https://[host]/apis/coupon/v1/passbooks/{id}
GET https://[HOST]/apis/coupon/v1/passbooks/88432496881
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "type" : "event_ticket",
		 "images" : {
		 	 "icon" : {
		 		 "non_retina_uri" : "http://[host]/apis/coupon/
		 		 v1/download/48a466863e444447369d1cdf076e8f44",
		 		 "retina_uri" : "http://[host]/apis/coupon/
		 		 v1/download/d482a056c0297d78ae0056dc4fcd91de"
		 	},
		 	 "logo" : {
		 		 "non_retina_uri" : "http://[host]/apis/coupon/
		 		 v1/download/c9c8e0910ca61bf17474f7b5c23e88f0",
		 		 "retina_uri" : "http://[host]/apis/coupon/
		 		 v1/download/f04e089ce88710bd8c7a7f13639d4b15"
		 	},
		 	 "thumbnail" : {
		 		 "non_retina_uri" : "http://[host]/apis/coupon/
		 		 v1/download/f8efb66f6b73c417f506f51011189647",
		 		 "retina_uri" : "http://[host]/apis/coupon/
		 		 v1/download/bc0f4d8669b8b72c6657d6c2c8d2d83b"
		 	}
		 },
		 "fields" : {
		 	 "header" : [
			 	 {
			 		 "key" : "HCE",
			 		 "label" : "Event",
			 		 "value" : "BC"
			 	 }
			 ],
		 	 "primary" : [
			 	 {
			 		 "key" : "HETNM",
			 		 "label" : "Event name",
			 		 "value" : "Music Concert"
			 	 }
			 ],
		 	 "secondary" : [
			 	 {
			 		 "key" : "HCEATND",
			 		 "label" : "Attendee",
			 		 "value" : "John Smith"
			 	 }
			 ],
		 	 "auxiliary" : [
			 	 {
			 		 "key" : "HCELOC",
			 		 "label" : "Location",
			 		 "value" : "London, UK"
			 	 }
			 ],
		 	 "back" : [
			 	 {
			 		 "key" : "DESC",
			 		 "label" : "Description",
			 		 "value" : "Music Concert in London"
			 	 }
			 ]
		 },
		 "general" : {
		 	 "description" : "Music Concert Ticket",
		 	 "logo_text" : "Band Concert"
		 }
	 }
}

Delete A Passbook

DELETE https://[host]/apis/coupon/v1/passbooks/{id}
DELETE https://[HOST]/apis/coupon/v1/passbooks/88432496881
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

Get Balance

To get your account's balance you must send a balance GET request.

https://[HOST]/apis/coupon/v1/balance

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account balance. Otherwise, an error is returned.

Get Balance

GET https://[HOST]/apis/coupon/v1/balance
GET https://[HOST]/apis/coupon/v1/balance
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}

Errors

SMS Coupons API uses 2 levels of errors. Conventional HTTP status codes and application error codes.

SMS Coupons API raises errors for many reasons (authentication, invalid parameters, network / server errors etc.). Consult the detailed HTTP status codes and application error codes tables for detailed explanation of response codes.

Application Errors

SMS Coupons API returns errors in an array of objects.

Object Attributes
  • code numeric

    Application error code identifying error.

  • message string

    A human-readable message providing more details about the error.

Errors

{
	 "status_code" : 404,
	 "status_message" : "Not found",
	 "errors" : [
		{
			 "code" : 1007,
			 "message" : "URI not found"
		}
	 ]
}

HTTP Status Codes

200 OK Everything worked as expected.
201 Created Resource created successfully.
400 Bad Request The request was unacceptable, often due to invalid JSON format.
401 Unauthorized No valid API key provided.
404 Not Found The requested resource doesn't exist.
422 Unprocessable Request The request unprocessable, often due to invalid parameters.
500 Internal Server Error The service is temporarily unavailable.
503 Service Unavailable The service is temporarily unavailable.

Application Error Codes

400 Undefined coupon code Undefined parameter.
800 Invalid coupon code Invalid parameter.
801 Expired coupon code Expired parameter.
802 Redeem limit exceeded Coupon code redeem limit exceeded.
1001 Invalid token type Invalid parameter.
1002 Invalid username Invalid parameter.
1003 Invalid password Invalid parameter.
1004 Invalid authentication credentials Credentials provided is not correct.
1005 Invalid refresh token Invalid parameter.
1006 Insufficient balance User balance is not enough in order to process the request.
1007 URI not found Request URI not found.
1009 Invalid access token Access token is invalid.
1101 Invalid JSON format Invalid JSON structure.
1102 Unable to process request Unable to process request.
1300 SMS Coupons unavailable You account does not have permissions to use SMS Coupons service.
1301 Invalid catalog Invalid parameter.
1302 Invalid name Invalid parameter.
1303 Invalid contact Invalid parameter.
1304 Invalid name Invalid parameter.
1305 Invalid phone Invalid parameter.
1307 Invalid file format Invalid parameter.
1308 Invalid target catalog Invalid parameter.
1401 Invalid campaign Invalid parameter.
1402 Invalid campaign name Invalid parameter.
1403 Invalid campaign type Invalid parameter.
1404 Invalid campaign text type Invalid parameter.
1405 Invalid redemption type Invalid parameter.
1406 Invalid redemption max repetitions Invalid parameter.
1407 Invalid redemption expiration date Invalid parameter.
1408 Invalid Coupon Source Invalid parameter.
1409 Invalid campaign brand Invalid parameter.
1410 Invalid campaign SMS Invalid parameter.
1411 Invalid campaign SMS text Invalid parameter.
1412 Invalid campaign SMS originator. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-) or 14 numeric characters (0-9). Special characters are not allowed. Invalid parameter.
1413 Campaign SMS text placeholder [CODE] not provided SMS must contain the [CODE] placeholder.
1414 Campaign SMS text placeholder [LINK] not provided SMS must contain the [LINK] placeholder.
1415 Invalid campaign expiration date Invalid parameter.
1417 Invalid campaign broadcast date Invalid parameter.
1418 Invalid campaign Invalid parameter.
1419 Invalid message length Invalid message length. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table , you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table , because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
1501 Invalid template Invalid parameter.
1601 Invalid group Invalid parameter.
1602 Invalid group name Invalid parameter.
1604 Invalid group type Invalid parameter.
1605 Invalid coupon Invalid parameter.
1606 Invalid coupon code Invalid parameter.
1607 Invalid coupon svg image Invalid parameter.
1608 You cannot update svg coupon Update coupon svg is not permitted
1609 Coupon group is not on same group requested You cannot add a coupon to group with different type.
1610 Invalid target group Invalid parameter.
1611 Invalid coupon Invalid parameter.
1612 Invalid coupon generate parameters Invalid parameter.
1613 Invalid coupon count Invalid parameter.
1614 Invalid coupon digits Invalid parameter.
1615 Invalid target group Invalid parameter.
1701 Invalid passbook Invalid parameter.
1702 Invalid passbook image position Invalid parameter.
1703 Invalid passbook type Invalid parameter.
1704 Invalid passbook images Invalid parameter.
1705 Invalid passbook icon image Invalid parameter.
1706 Invalid passbook logo image Invalid parameter.
1709 Invalid passbook background image Invalid parameter.
1710 Invalid passbook strip image Invalid parameter.
1711 Invalid passbook thumbnail image Invalid parameter.
1712 Invalid passbook footer image Invalid parameter.
1713 Invalid passbook fields Invalid parameter.
1714 Invalid passbook primary fields Invalid parameter.
1715 Invalid passbook primary fields (max 1) Invalid parameter.
1716 Invalid passbook primary fields (max 2) Invalid parameter.
1717 Invalid passbook header fields (max 3) Invalid parameter.
1718 Invalid passbook secondary fields (max 4) Invalid parameter.
1719 Invalid passbook auxiliary fields (max 4) Invalid parameter.
1720 Invalid passbook auxiliary fields (max 5) Invalid parameter.
1721 Invalid passbook back fields (max 15) Invalid parameter.
1722 Invalid passbook relevant places exceeded (max 10) Invalid parameter.
1723 Invalid passbook description Invalid parameter.
1724 Invalid passbook (boarding pass) transit type Invalid parameter.
1725 Invalid passbook expiration date Invalid parameter.
1726 Invalid passbook background color Invalid parameter.
1727 Invalid passbook label color Invalid parameter.
1728 Invalid passbook foreground color Invalid parameter.
1729 Invalid passbook general information Invalid parameter.
1730 Invalid passbook relevant date Invalid parameter.
1731 Invalid passbook fields (must have unique keys) Invalid parameter.
1732 Invalid passbook lock screen title Invalid parameter.
1801 Invalid code type Invalid parameter.
1803 Invalid code text type Invalid parameter.
1805 Service temporary unavailable Service temporary unavailable.
1901 File not found Request file not found.
1902 Invalid owner type Invalid parameter.
1903 Invalid file type Invalid parameter.
1904 Undefined file upload parameters Invalid parameter.
1905 Invalid file mime type Invalid parameter.
1906 Invalid csv separator Invalid parameter.
1907 Invalid value for remove duplicates Invalid parameter.
1908 Invalid parameter for file structure Invalid parameter.
1911 File columns is the same Invalid parameter.
1912 Invalid catalog name column Invalid parameter.
1913 Invalid catalog number column Invalid parameter.
1914 Catalog columns cannot be the same Invalid parameter.
1915 Invalid group code column Invalid parameter.
1916 Invalid group svg column Invalid parameter.
1917 Group columns cannot be the same Invalid parameters.
1918 Invalid group svg file format Invalid parameter.
1919 Image not found Request image not found.

The AUTH Request

POST

The auth request is used to authenticate and gain access to the SMS Coupons API requests.

Parameters
  • type required predefined string "access_token" , "refresh_token"

    The type of the auth request. Can be "access_token" to reset connection or "refresh_token" to refresh connection.

  • username required for type "access_token" string

    The username of your SMS Coupons API account.

  • password required for type "access_token" string

    The password of your SMS Coupons API account.

  • refresh_token required for type "refresh_token" string

    The refresh_token. Used when refreshing the connection.

Response

If the request succeeds, an authentication object is returned. An access_token for SMS Coupons API requests and a refresh_token to refresh the connection are provided. Returns an error on failure.

Object Attributes
  • access_token string

    The access_token to use with the SMS Coupons API requests.

  • validity_period numeric

    The validity period of access_token and refresh_token.

  • refresh_token string

    The refresh_token to use when refreshing the connection.

/auth

POST https://[HOST]/apis/auth
POST https://[HOST]/apis/auth
Content-Type : application/json
{
	 "type" : "access_token",
	 "username" : "myusername",
	 "password" : "mypassword"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
	 	 "validity_period" : 1800,
	 	 "refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
	 }
}

The BALANCE Request

GET

The balance GET request is used to get an account's balance.

Response

If the request succeeds, an object with the current account's balance is returned. Returns an error on failure.

Object Attributes
  • balance string

    The balance of your account.

/balance

GET https://[HOST]/apis/coupon/v1/balance
GET https://[HOST]/apis/coupon/v1/balance
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
			 "balance" : "7845.3500"
	 }
}

The CATALOGS Request

GET

The catalogs GET request is used to get all catalogs.

Response

If the request succeeds, an array of catalogs is returned. Returns an error on failure.

Object Attributes
  • catalogs array

    Array of catalog objects.

    • id numeric

      The id of catalog.

    • name string

      The name of catalog.

    • total_contacts numeric

      Total number of contacts in catalog

  • total_catalogs numeric

    Total number of catalogs returned.

/catalogs

GET https://[HOST]/apis/coupon/v1/catalogs
GET https://[HOST]/apis/coupon/v1/catalogs
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
       "catalogs" : [
             {
                 "id" : 10049,
                 "name" : "Catalog #1",
                 "total_contacts" : 10
             },
             {
                 "id" : 10050,
                 "name" : "Catalog #2",
                 "total_contacts" : 15
             }
         ],
         "total_catalogs" : 2
   }
}

The CATALOGS Request

POST

The catalogs POST request is used to create a catalog.

Body Parameters
  • name required string

    The name of catalog.

  • file optional string

    File reference.

Response

If the request succeeds, an object with the catalog id is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of created catalog.

/catalogs

POST https://[HOST]/apis/coupon/v1/catalogs
POST https://[HOST]/apis/coupon/v1/catalogs
Content-Type : application/json
{
	 "name" : "Catalog #1",
	 "file" : "ca1cfb80b50b411033aa30ea2199af25"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 3202
	 }
}

The CATALOGS/{ID} Request

GET

The catalogs/{id} GET request is used to get a catalog.

URL Parameters
  • id required numeric

    The id of catalog.

Response

If the request succeeds, a catalog object is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of catalog.

  • name string

    The name of catalog.

  • total_contacts numeric

    Total number of contacts in catalog

/catalogs/{id}

GET https://[HOST]/apis/coupon/v1/catalogs/{id}
GET https://[HOST]/apis/coupon/v1/catalogs/10049
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "id" : 10049,
         "name" : "Catalog #1",
         "total_contacts" : 10
	 }
}

The CATALOGS Request

PUT

The catalogs/{id} PUT request is used to update catalogs.

URL Parameters
  • id required numeric

    The id of catalog.

Body Parameters
  • name required string

    The name of catalog.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/catalogs/{id}

PUT https://[HOST]/apis/coupon/v1/catalogs/{id}
PUT https://[HOST]/apis/coupon/v1/catalogs/10049
Content-Type : application/json
{
	 "name" : "Catalog #1"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

The CATALOGS Request

DELETE

The catalogs/{id} DELETE request is used to delete a catalog.

URL Parameters
  • id required numeric

    The id of catalog.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/catalogs/{id}

DELETE https://[HOST]/apis/coupon/v1/catalogs/{id}
DELETE https://[HOST]/apis/coupon/v1/catalogs/10049
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

The CONTACTS Request

GET

The contacts GET request is used to get contacts of a catalog.

URL Parameters
  • id required numeric

    The id of catalog.

Response

If the request succeeds, an array of contacts is returned. Returns an error on failure.

Object Attributes
  • contacts array

    Array of contact objects.

    • id numeric

      The id of contact.

    • fullname string

      The fullname of contact.

    • phone numeric

      The phone of contact.

  • total_contacts numeric

    Total number of catalog contacts.

/catalogs/{id}/contacts

GET https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts
GET https://[HOST]/apis/coupon/v1/catalogs/10070/contacts
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
       "contacts" : [
             {
                 "id" : 109607353,
                 "fullname" : "Contact #1",
                 "phone" : 44778855996
             },
             {
                 "id" : 109671354,
                 "fullname" : "Contact 2",
                 "phone" : 44778765996
             }
         ],
         "total_contacts" : 2
   }
}

The CONTACTS Request

POST

The contacts POST request is used to add a new contact to a catalog.

URL Parameters
  • id required numeric

    The id of catalog.

Body Parameters
  • name required string

    The contact name.

  • phone required numeric

    The contact phone.

Response

If the request succeeds, an object with the contact id is returned. Returns an error on failure.

Object Attributes
  • id string

    The id of created contact.

/catalogs/{id{/contacts

POST https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts
POST https://[HOST]/apis/coupon/v1/catalogs/10049/contacts
Content-Type : application/json
{
	 "name" : "Contact #1",
	 "phone" : "447788556321"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "id" : 362202
	 }
}

The CONTACTS/{CID} Request

GET

The contacts GET request is used to get a contact from a catalog.

URL Parameters
  • id required numeric

    The id of catalog.

  • cid required numeric

    The id of contact.

Response

If the request succeeds, a contact object is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of contact.

  • fullname string

    The fullname of contact.

  • phone numeric

    The phone of contact.

/catalogs/{id}/contacts/{cid}

GET https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts/{cid}
GET https://[HOST]/apis/coupon/v1/catalogs/10070/contacts/109607353
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
         "id" : 109607353,
         "fullname" : "Contact #1",
         "phone" : 44778855996
   }
}

The CONTACTS Request

PUT

The contacts PUT request is used to update a contact.

URL Parameters
  • id required numeric

    The id of catalog.

  • cid required numeric

    The id of contact.

Body Parameters
  • name required string

    The name of contact.

  • phone required numeric

    The phone of contact.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/catalogs/{id}/contacts/{cid}

PUT https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts/{cid}
PUT https://[HOST]/apis/coupon/v1/catalogs/10070/contacts/109607353
Content-Type : application/json
{
   "name" : "Contact #1",
   "phone" : 447788556322
}
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The CONTACTS Request

DELETE

The contacts DELETE request is used to delete a contact.

URL Parameters
  • id required numeric

    The id of catalog.

  • cid required numeric

    The id of contact.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/catalogs/{id}/contacts/{cid}

DELETE https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts/{cid}
DELETE https://[HOST]/apis/coupon/v1/catalogs/10070/contacts/109607353
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The CONTACTS/MOVE Request

POST

The contacts POST request is used to move a contact between catalogs.

URL Parameters
  • id required numeric

    The id of source catalog.

Body Parameters
  • target_catalog_id required numeric

    The id of target catalog.

  • contact_id required numeric

    The id of contact.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/catalogs/{id}/contacts/move

POST https://[HOST]/apis/coupon/v1/catalogs/{id}/contacts/move
POST https://[HOST]/apis/coupon/v1/catalogs/10070/contacts/move
Content-Type : application/json
{
   "target_catalog_id" : 10071,
   "contact_id" : 109607353
}
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The GROUPS Request

GET

The groups GET request is used to get all groups.

Response

If the request succeeds, an array of groups is returned. Returns an error on failure.

Object Attributes
  • groups array

    Array of group objects.

    • id numeric

      The id of group.

    • name string

      The name of group.

    • type predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417" , "2dbarcode_aztec"

      The type of group.

    • total_codes numeric

      Total number of codes in group

  • total_groups numeric

    Total number of groups returned.

/groups

GET https://[HOST]/apis/coupon/v1/groups
GET https://[HOST]/apis/coupon/v1/groups
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
       "groups" : [
           {
               "id" : 10049,
               "name" : "Group #1",
               "type" : "qr_code",
               "total_codes" : 10
           },
           {
               "id" : 10070,
               "name" : "Group #7",
               "type" : "2dbarcode_pdf417",
               "total_codes" : 2
           },
           {
               "id" : 10073,
               "name" : "Group #7",
               "type" : "2dbarcode_pdf417",
               "total_codes" : 2
           }
        ],
        "total_groups" : 3
   }
}

The GROUPS Request

POST

The groups POST request is used to create a group.

Body Parameters
  • name required string

    The name of group.

  • type required predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417" , "2dbarcode_aztec"

    The type of group.

  • file optional string

    File reference.

Response

If the request succeeds, an object with the group id is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of group.

/groups

POST https://[HOST]/apis/coupon/v1/groups
POST https://[HOST]/apis/coupon/v1/groups
Content-Type : application/json
{
	 "name" : "Group #10",
     "type" : "2dbarcode_datamatrix",
	 "file" : "ca1cfb80b50b411033aa30ea2199af25"
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 10075
	 }
}

The GROUPS/{ID} Request

GET

The groups GET request is used to get a group.

URL Parameters
  • id required numeric

    The id of group.

Response

If the request succeeds, a group object is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of group.

  • name string

    The name of group.

  • type predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417" , "2dbarcode_aztec"

    The type of group.

  • total_codes numeric

    Total number of codes in group

/groups/{id}

GET https://[HOST]/apis/coupon/v1/groups/{id}
GET https://[HOST]/apis/coupon/v1/groups/10073
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "id" : 10073,
         "name" : "Group #6",
         "type" : "2dbarcode_aztec",
         "total_codes" : 10
	 }
}

The GROUPS Request

PUT

The groups PUT request is used to update a group.

URL Parameters
  • id required numeric

    The id of the group.

Body Parameters
  • name required string

    The name of the group.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/groups/{id}

PUT https://[HOST]/apis/coupon/v1/groups/{id}
PUT https://[HOST]/apis/coupon/v1/groups/10049
Content-Type : application/json
{
	 "name" : "Group #1"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

The GROUPS Request

DELETE

The groups DELETE request is used to delete a group.

URL Parameters
  • id required numeric

    The id of group.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/groups/{id}

DELETE https://[HOST]/apis/coupon/v1/groups/{id}
DELETE https://[HOST]/apis/coupon/v1/groups/10050
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

The COUPONS Request

GET

The coupons GET request is used to get coupons of a group.

URL Parameters
  • id required numeric

    The id of group.

Response

If the request succeeds, an array of coupons is returned. Returns an error on failure.

Object Attributes
  • coupons array

    Array of coupon objects.

    • id numeric

      The id of coupon.

    • code string

      The code of coupon.

    • type predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417" , "2dbarcode_aztec"

      The type of coupon.

  • total_coupons numeric

    Total number of group coupons.

/groups/{id}/coupons

GET https://[HOST]/apis/coupon/v1/groups/{id}/coupons
GET https://[HOST]/apis/coupon/v1/groups/10070/coupons
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
       "coupons" : [
           {
               "id" : 109607353,
               "code" : "ab7dasd913jasdoj1004",
               "type" : "image"
           },
           {
               "id" : 109671354,
               "code" : "cab7dasd913jasdoj1005",
               "type" : "image"
           }
        ],
        "total_coupons" : 2
   }
}

The COUPONS Request

POST

The coupons POST request is used to add a new coupon to a group.

URL Parameters
  • id required numeric

    The id of group.

Body Parameters
  • code required string

    The code of coupon.

Response

If the request succeeds, an object with the coupon id is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of coupon.

/groups/{id}/coupons

POST https://[HOST]/apis/coupon/v1/groups/{id}/coupons
POST https://[HOST]/apis/coupon/v1/groups/10073/coupons
Content-Type : application/json
{
	 "code" : "12319237193as111s"
}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "id" : 3622113
	 }
}

The COUPONS/{CID} Request

GET

The coupons GET request is used to get a coupon from a group.

URL Parameters
  • id required numeric

    The id of group.

  • cid required numeric

    The id of coupon.

Response

If the request succeeds, a coupon object is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of coupon.

  • code string

    The code of coupon.

  • type predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417" , "2dbarcode_aztec"

    The type of coupon.

/groups/{id}/coupons/{cid}

GET https://[HOST]/apis/coupon/v1/groups/{id}/coupons/{cid}
GET https://[HOST]/apis/coupon/v1/groups/10070/coupons/109607353
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
         "id" : 109607353,
         "code" : "ab7dasd913jasdoj1004",
         "type" : "image"
   }
}

The COUPONS Request

PUT

The coupons PUT request is used to update a coupon.

URL Parameters
  • id required numeric

    The id of group.

  • cid required numeric

    The id of coupon.

Body Parameters
  • code required string

    The code of coupon.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/groups/{id}/coupons/{cid}

PUT https://[HOST]/apis/coupon/v1/groups/{id}/coupons/{cid}
PUT https://[HOST]/apis/coupon/v1/groups/10070/coupons/109607353
Content-Type : application/json
{
   "code" : "ab7dasd913jaAAoj1224"
}
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The COUPONS Request

DELETE

The coupons DELETE request is used to delete a coupon.

URL Parameters
  • id required numeric

    The id of group.

  • cid required numeric

    The id of coupon.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/groups/{id}/coupons/{cid}

DELETE https://[HOST]/apis/coupon/v1/groups/{id}/coupons/{cid}
DELETE https://[HOST]/apis/coupon/v1/groups/10070/coupons/1000245
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The COUPONS/MOVE Request

POST

The coupons POST request is used to move a coupon between groups.

URL Parameters
  • id required numeric

    The id of source group.

Body Parameters
  • target_group_id required numeric

    The id of target group.

  • coupon_id required numeric

    The id of coupon.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/groups/{id}/coupons/move

POST https://[HOST]/apis/coupon/v1/groups/{id}/coupons/move
POST https://[HOST]/apis/coupon/v1/groups/10070/coupons/move
Content-Type : application/json
{
   "target_group_id" : 10073,
   "coupon_id" : 109607353
}
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : ""
}

The UPLOAD Request

POST

The upload POST request is used to upload a file.

Body Parameters
  • file required file

    The file you want to upload.

  • owner_type required predefined string "catalog" , "group", "passbook"

    The owner type of file.

  • csv_separator required for owner type "catalog" or "group" and for file type "csv" predefined string ";" , ","

    The csv separator.

  • remove_duplicates required for owner type "catalog" or "group" predefined string "true" , "false"

    Remove duplicates entries in the file.

  • catalog_name_column required for owner type "catalog" predefined string "left" , "right"

    Names column position in file.

  • catalog_number_column required for owner type "catalog" predefined string "left" , "right"

    Numbers column position in file.

  • group_code_column required for owner type "group" predefined string "left" , "right"

    Codes column position in file.

  • group_svg_column required for owner type "group" and group type "image" predefined string "left" , "right"

    Images column position in file.

  • passbook_image_position required for owner type "passbook" predefined string "background" , "footer", "icon", "logo", "strip", "thumbnail"

    Passbook image position.

Response

If the request succeeds, an object including a file_reference is returned. Returns an error on failure.

Object Attributes
  • file_reference string

    The file_reference of uploaded file. It expires after 30 minutes and is deleted.

/upload

POST https://[HOST]/apis/coupon/v1/upload
POST https://[HOST]/apis/coupon/v1/upload
Content-Type : multipart/form-data
   "file" : "groups.csv",
   "owner_type" : "group",
   "csv_separator" : ";"
   "remove_duplicates" : "true"
   "group_code_column" : "left"
   "group_svg_column" : "right"

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "file_reference" : "ca1cfb80b50b411033aa30ea2199af25"
	 }
}

The DOWNLOAD Request

GET

The download GET request is used to download previously uploaded files.

URL Parameters
  • reference required string

    The reference of uploaded file.

Response

If the request succeeds, an image file is returned. Returns an error on failure.

/download/{reference}

GET https://[HOST]/apis/coupon/v1/download/{reference}
GET https://[HOST]/apis/coupon/v1/download/ca1cfb80b50b411033aa30ea2199af25
Content-Type : image/jpeg
        ! 1
A"v∂w∑89Qatµ67xq2#≥4÷óÅë±BR3s$UW°r“ìTï’ñX—b≤S%5uV'◊ò∏Çí¢Cg¬cîG(!1AQaq"6Åë±2r≤s≥tu°B¬#3457¡Rbí“$T¥—ÇSÉìU¢Cî‘%”„eV·£√D&‚cd§'ˇ⁄?ø¿" " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " " "¯û}àÕ©È4√I˝ÛØ8ÜõO_Gyk4§ø∂?Mcfir∞Ô_ó9¨ú@5‚-6¶±§'NÁb‡µ^  ∫V9m5#ªÈ%"Dˆ‘J˚›:åµæfi◊ÓÈÙ[π+”,2;‹jƒ‹Ó»y}gsÕiÌ∏/  îx±ºã笋∫˙EÃÁÃHç‰p;≤Zªç∞‹µ8Pî˚´>âGâfiQüB#1óó`oX-.óz€V
óùÄëL‘¶î  "Ï;ãÊi∞Í˙{Ø^h÷ ŸW¿
hIÏ©ÏY‹js@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D
@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@DP’»O0
õb‰∏ñõB#°
Öcão3-'≥:LGg^=‘»êÂ-5+&^‚ p∫˝√låg-∏u»ÔÔw6∑·ΩÁ⁄lt˚´sÎ
≥co˜;]Jw|ì#‹í7‹™∆ñ~h—M¶èH€ù:0ıÊiY≤?pfièYSfæÔfiKùFvWÈ*
fi≠^—'ÿ/{=≈Ø\z«¬AZ4˘ª≥∆—ÏÜ6CÌç¨<Õˆ„∆¥’k-u^ì#$9:◊%∂Z:óbç∂
ô+2˚ù‚!ùáÅ6€hn/Ôû|
dL˚ß?∏∞˙ƒÓáí-¥À«Ö“À'‹è›X÷€Ãìñ5Aπ¡®[22Î∞¥KRL˝“v‚÷√©óflOAù∂·}Ö§±]Ã|.ûüqåo∫µ˚Æs‰i›X$∞Åæ€ómÚª‹X÷Áó|õº5ù…ë¡Ô(‘i°Ø∆Ë—€◊±>£Jáûfi¬%vıØÏ+O…Èp?Â,üÙ˚ã_ªÂ.Gº¸¶Ø<%˚ë˜V:∏‹ªó!A5}∑∂m´e◊£oÊ∑¨6]‚Ë}÷†ÃàŸu˝¡ö∂⁄˚^»Ê≥”l#wä…ˆ‹◊Å∫›õ∫˘πoumJAıâ˜#,”ÍŒHnM7yÔÃÚ+ ∏Ú˝æì]ÿfi–dP…I9PÕ“&?SbÛ)4±.2€[Nt5í—fiA¯7∆€¢—÷ó÷∞Cp·FOméHùÿ|¿–ˆÉÔò‡A°i°^̪ø˜~“ªeÓùysql◊VKiÂ|±Ã‹34ù»cÿÊÂu36≠65¡s
çÉÜ‚˘≈
‘∫|≤ä≤˙øƒÈ‚¢=îF•%á…&i)Õ√m¬#2%§»R
[Lπ—µ;ç&RÍfigFÔZH®Ò£ƒU¯—ı[MsJ∂÷,MlÓ†d¨=π^–·_≠çz°èY$@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@D@DZ;¥y˘¶5ñaë`™¨Õrª¸Zi’›9èU@M4kV⁄Cí´ikk^R%¿SÑá¸6÷€nuG|‘ïK;á7Nø¶A´â-m¨Óùù„›ú≤¥»∆:çu*⁄êH∆î òwqÛv–€∫µ∆àËÔ.Ø≠_íNÍ6˜aÙ≥;fi¿Á6†;-COöN`@¿÷^h’‚"óI‰/´©ì/\eÙµÌü¯*q™¯VÓvó∏G˝ë∏A͡sÅ∫’`¥2}∑9ÅiS˙«Ÿ‚,Ùk¢{ìD¡ˇsº+Y˘ùm7ú_¿∫≥Øhˇ≈ù•ÓClÍ~˙—=:xî_∫3∂¸∑ö—Ù≠BÒÓ˛Ñq∞}“ıØ‹˙≈nG∏˝K±c;ÊïÁ⁄llumg
        
        
        
      

The TEMPLATES Request

GET

The templates GET request is used to get templates. You can create and customize reusable templates through our web portal.

Response

If the request succeeds, an array of templates is returned. Returns an error on failure.

Object Attributes
  • templates array

    Array of template objects.

    • id numeric

      The id of template.

    • name string

      The name of template.

    • create_date date

      The creation date of template.

  • total_templates numeric

    Total number of templates returned.

/templates

GET https://[HOST]/apis/coupon/v1/templates
GET https://[HOST]/apis/coupon/v1/templates
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
    	 "templates" : [
    		{
    			 "id" : 10040,
    			 "name" : "Template #1",
    			 "create_date" : ""2015-11-15 12:00:00"
    		}
      	 ],
    	 "total_templates" : 1
	 }
}

The CAMPAIGNS Request

GET

The campaigns GET request is used to get campaigns.

Response

If the request succeeds, an array of campaigns is returned. Returns an error on failure.

Object Attributes
  • campaigns array

    Array of campaign objects.

    • id numeric

      The id of campaign.

    • name string

      The name of campaign.

    • group_id numeric

      The group id which contains the coupons used of this campaign.

    • group_name string

      The group name which contains the coupons used of this campaign.

    • broadcast_date date

      The broadcast date of campaign.

    • total_coupons numeric

      Total number of coupons in campaign.

    • total_cost numeric

      Total cost of campaign.

  • total_campaigns numeric

    Total number of campaigns returned.

/campaigns

GET https://[HOST]/apis/coupon/v1/campaigns
GET https://[HOST]/apis/coupon/v1/campaigns
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
       "campaigns" : [
            {
               "id" : 10001,
               "name" : "Campaign #1",
               "group_id" : "",
               "group_name" : "",
               "broadcast_date" : "2015-03-10 10:00:00",
               "total_coupons" : 100,
               "total_cost" : "9.9000"
            },
            {
               "id" : 10002,
               "name" : "Campaign #2",
               "group_id" : 10021,
               "group_name" : "Group #1",
               "broadcast_date" : "2015-03-11 07:00:00",
               "total_coupons" : 225,
               "total_cost" : "19.9000"
            }
        ],
        "total_campaigns" : 2
	 }
}

The CAMPAIGNS Request

POST

The campaigns POST request is used to create a campaign.

Body Parameters
  • name required string

    The campaign name.

  • brand required string

    The brand name that will appear in the coupon links of your campaign.

  • expiration_date optional date

    The campaign datetime of expiration.

  • template_id optional numeric

    The template that will be shown to the user when link is opened.

Response

If the request succeeds, an object with the campaign id is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of created campaign.

/campaigns

POST https://[HOST]/apis/coupon/v1/campaigns
POST https://[HOST]/apis/coupon/v1/campaigns
Content-Type : application/json
{
   "name" : "Discount Campaign #1",
   "brand" : "ecommerce-discounts",
   "expiration_date" : "2015-12-12 09:00:00",
   "template_id" : 1002
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
    	 "id" : 12354
	 }
}

The CAMPAIGNS/{ID} Request

GET

The campaigns/{id} GET request is used to get a campaign.

URL Parameters
  • id required numeric

    The id of campaign.

Response

If the request succeeds, a campaign object and an array of it's coupons are returned. Returns an error on failure.

Object Attributes
  • campaign Object

    campaign object.

    • id numeric

      The id of campaign.

    • name string

      The name of campaign.

    • group_id numeric

      The group id which contains the coupons of campaign.

    • group_name string

      The group name which contains the coupons of campaign.

    • broadcast_date date

      The broadcast date of campaign.

    • expiration_date date

      The expiration date of campaign.

    • total_coupons numeric

      Total number of coupons of campaign.

    • coupons_opened numeric

      Total number of opened coupons of campaign.

    • coupon_redeemed numeric

      Total number of redeemed coupons of campaign.

    • total_cost numeric

      Total cost of campaign.

  • coupons array

    Array of coupon objects.

    • code_id numeric

      The id of code.

    • code numeric

      The code of coupon.

    • create_date numeric

      The creation date of coupon.

    • group_id numeric

      The group id of coupon.

    • group_name string

      The group name of coupon.

    • phone numeric

      The recipient phone.

    • open_date date

      The date that coupon was first viewed.

    • redemption_mode predefined string "http_api" , "external"

      The redemption mode.

    • max_repetitions numeric

      Maximum number of redemptions allowed.

    • repetitions numeric

      Total number of redemptions completed.

    • cost numeric

      cost of coupon.

    • message string

      The sms message text.

    • redeemed_dates array

      Array of redeemed dates of coupon.

    • status predefined string "redeemed" , "opened" , "delivered" , "pending"

      status of coupon.

    • type predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417" , "2dbarcode_aztec"

      type of coupon.

/campaigns/{id}

GET https://[HOST]/apis/coupon/v1/campaigns/{id}
GET https://[HOST]/apis/coupon/v1/campaigns/1001
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "campaign" : {
			 "id" : 10001,
			 "name" : "Campaign #12",
			 "group_id" : "",
			 "group_name" : "",
			 "broadcast_date" : "2015-03-12 09:10:00",
			 "expiration_date" : "",
			 "total_coupons" : 1,
			 "coupons_opened" : 1,
			 "coupons_redeemed" : 0,
			 "total_cost" : "0.2000"
		},
		 "coupons" : [
			{
				 "code_id" : 215704,
				 "code" : "ASAAA2923984792",
				 "create_date" : "2015-03-12 15:10:00",
				 "group_id" : "",
				 "group_name" : "",
				 "phone" : "447711525668",
				 "open_date" : "2015-03-12 15:15:00",
				 "max_repetitions" : 0,
				 "repetitions" : 0,
				 "redemption_mode" : "external",
				 "cost" : "0.2000",
				 "message" : Your coupon link:  http://[host]/coupon/
				 mcoupons/[brand]/1b2842a70858ea88bb89d6df69",
				 "redeemed_dates" : [],
				 "status" : "opened",
				 "type" : "qr_code"
			}
		 ]
	 }
}

The SINGLE_COUPON Request

POST

The single_coupon POST request is used to send a single coupon.

Body Parameters
  • campaign_id required numeric

    The id of campaign.

  • phone required numeric

    The recipient phone of the coupon.

  • coupon_type required predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417", "2dbarcode_aztec"

    The type of coupon.

  • coupon_text_type required for coupon_type "text" predefined string "simple_text" , "template"

    The text type of coupon.

  • coupon required object

    Coupon parameters.

    • source required predefined string "select" , "generate"

      The coupon source.

    • config required object

      The coupon configuration.

      • code required for source "select" string

        The coupon code.

      • coupon_digits required for source "generate" numeric

        The number of code digits.

      • code_type required for source "generate" predefined string "alpha_uppercase" , "alpha_lowercase", "numeric", "alphanum_uppercase", "alphanum_lowercase"

        The type of generated code.

  • template_id required numeric

    The template id.

  • sms required object

    SMS parameters.

    • text required string

      The message text of SMS.

    • originator required string

      The sender of SMS that will be displayed.

  • redemption optional object

    Coupon redemption parameters.

    • type required predefined string "http_api" , "external"

      The redemption type of coupon.

    • config required object

      Coupon redemption configuration.

      • max_repetitions required for type "http_api" numeric

        The maximum number of redemptions allowed.

      • expiration_date required for type "http_api" date

        The expiration date of coupon.

  • passbook_id optional numeric

    The id of passbook.

Response

If the request succeeds, a single coupon object is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of created coupon.

  • redemption_api_key string

    The redemption api key provided by your single_coupon or broadcast request. Used with redeem requests for coupon redemptions.

  • code string

    The code of created coupon.

  • broadcast_date date

    The broadcast date of created coupon.

  • expiration_date date

    The expiration date of created coupon.

  • cost numeric

    The cost of created coupon.

/single_coupon

POST https://[HOST]/apis/coupon/v1/single_coupon
POST https://[HOST]/apis/coupon/v1/single_coupon
Content-Type : application/json
{
	"campaign_id" : 10051,
	"phone" : 44699992222,
    "coupon_type" : "2dbarcode_aztec",
    "coupon_text_type" : "template",
    "coupons" : {
        "source" : "generate",
        "config" : {
            "coupon_digits" : 12,
            "code_type" : "numeric"
        }
    },
    "template_id" : 1023,
    "sms" : {
        "text" : "Get your coupon here: [LINK]",
        "originator" : "MobiWeb"
    },
    "redemption" : {
        "type" : "http_api",
        "config" : {
            "max_repetitions" : 2,
            "expiration_date" : "2015-12-31 11:00:00"
        }
     },
     "passbook_id" : 1223
}
{
	 "status_code" : 200,
	 "OK" : "Created",
	 "payload" : {
	 	 "id" : 3002202
	 	 "redemption_api_key" : das9dj320ej39rj29rj3b4htlk54324
	 	 243djasd3232r4tu5u,
         "code" : "12038zk855ZJ1HU"
         "broadcast_date" : "2015-11-15 19:00:00"
         "expiration_date" : "2015-12-31 11:00:00"
         "cost" : 0.0901
	 }
}

The BROADCAST Request

POST

The broadcast POST request is used to send campaigns of multiple coupons.

Body Parameters
  • campaign_name required string

    The name of campaign.

  • catalog_id required numeric

    The id of catalog.

  • coupon_type required predefined string "text" , "qr_code", "image" , "2dbarcode_datamatrix" , "2dbarcode_pdf417", "2dbarcode_aztec"

    The type of coupons.

  • coupon_text_type required for coupon_type "text" predefined string "simple_text" , "template"

    The text type of coupons.

  • coupons required object

    Coupon parameters.

    • source required predefined string "select" , "generate"

      The coupon source.

    • config required object

      The coupon configuration.

      • group_id required for source "select" numeric

        The group id.

      • coupon_count required for source "generate" numeric

        The number of total codes to be generated.

      • coupon_digits required for source "generate" numeric

        The number of code digits.

      • code_type required for source "generate" predefined string "alpha_uppercase" , "alpha_lowercase", "numeric", "alphanum_uppercase", "alphanum_lowercase"

        The type of generated code.

  • template_id required numeric

    The template id.

  • brand required string

    The brand name that will appear in the links of coupons.

  • broadcast_date required date

    The broadcast date of campaign.

  • sms required object

    SMS parameters.

    • text required string

      The message text of SMS.

    • originator required string

      The sender of SMS that will be displayed.

  • redemption optional object

    Coupon redemption parameters.

    • type required predefined string "http_api" , "external"

      The redemption type of coupon.

    • config required object

      Coupon redemption configuration.

      • max_repetitions required for type "http_api" numeric

        The maximum number of redemptions allowed.

      • expiration_date required for type "http_api" date

        The expiration date of coupon.

  • passbook_id optional numeric

    The id of passbook.

Response

If the request succeeds, a broadcast object is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of created campaign.

  • redemption_api_key string

    The redemption api key provided by your single_coupon or broadcast request. Used with redeem requests for coupon redemptions.

  • group_id numeric

    The group id of created campaign.

  • group_name string

    The group name of created campaign.

  • broadcast_date date

    The broadcast date of created campaign.

  • expiration_date date

    The expiration date of created campaign.

  • total_coupons numeric

    Total coupons of created campaign.

  • total_cost numeric

    Total cost of created campaign.

  • coupon_errors array

    Error occurred during sending.

    • code string

      The code of coupon.

    • phone numeric

      The phone of coupon.

    • error_code numeric

      The error code.

    • error_message string

      The error message.

/broadcast

POST https://[HOST]/apis/coupon/v1/broadcast
POST https://[HOST]/apis/coupon/v1/broadcast
Content-Type : application/json
{
	"campaign_name" : "Campaign #10",
	"catalog_id" : 3202,
    "coupon_type" : "qr_code",
    "coupon_text_type" : "template",
    "coupons" : {
        "source" : "generate",
        "config" : {
            "coupon_count" : 10,
            "coupon_digits" : 12,
            "code_type" : "alpha_lowercase"
        }
    },
    "template_id" : 1023,
    "brand" : "ecommerce-discounts",
    "broadcast_date" : "2015-12-31 10:00:00",
    "sms" : {
        "text" : "Get your coupon here: [LINK]",
        "originator" : "MobiWeb"
    },
    "redemption" : {
        "type" : "http_api",
        "config" : {
            "max_repetitions" : 2,
            "expiration_date" : "2015-12-31 18:00:00"
        }
     },
     "passbook_id" : 1223
}
{
	 "status_code" : 200,
	 "OK" : "Created",
	 "payload" : {
	 	 "id" : 3002202
	 	 "redemption_api_key" : das9dj320ej39rj29rj3b4htlk54324
	 	 243djasd3232r4tu5u,
         "code" : "12038zk855ZJ1HU"
         "broadcast_date" : "2015-11-15 19:00:00"
         "expiration_date" : "2015-12-31 11:00:00"
         "cost" : 0.0901
	 }
}

The PASSBOOKS Request

GET

The passbooks GET request is used to get all passbooks.

Response

If the request succeeds, an array of passbooks is returned. Returns an error on failure.

Object Attributes
  • passbooks array

    Array of passbook objects.

    • id numeric

      The id of passbook.

    • description string

      The description of passbook.

    • type predefined string "boarding_pass" , "coupon", "event_ticket" , "generic" , "store_card"

      The type of passbook.

  • total_passbooks numeric

    Total number of passbooks returned.

/passbooks

GET https://[HOST]/apis/coupon/v1/passbooks
GET https://[HOST]/apis/coupon/v1/passbooks
{
   "status_code" : 200,
   "status_message" : "OK",
   "payload" : {
       "passbooks" : [
           {
               "id" : 1078,
               "description" : "Live concert",
               "type" : "event_ticket"
           },
           {
               "id" : 1079,
               "description" : "Air ticket",
               "type" : "boarding_pass"
           }
        ],
        "total_passbooks" : 2
   }
}

The PASSBOOKS Request

POST

The passbooks POST request is used to create a passbook.

Body Parameters
  • type required predefined string "boarding_pass" , "coupon", "event_ticket" , "generic" , "store_card"

    The passbook type.

  • images object

    The images object.

    • icon required string

      Passbook icon image.

    • logo required string

      Passbook logo image.

    • background optional string

      Passbook background image.

    • footer optional string

      Passbook footer image.

    • strip optional string

      Passbook strip image.

    • thumbnail optional string

      Passbook thumbnail image.

  • fields object

    The fields object.

    • header optional array

      Passbook header fields.

      • key required string

        Field key.

      • label required string

        Field label.

      • value required string

        Field value.

    • primary optional array

      Passbook primary fields.

      • key required string

        Field key.

      • label required string

        Field label.

      • value required string

        Field value.

    • secondary optional array

      Passbook secondary fields.

      • key required string

        Field key.

      • label required string

        Field label.

      • value required string

        Field value.

    • auxiliary optional array

      Passbook auxiliary fields.

      • key required string

        Field key.

      • label required string

        Field label.

      • value required string

        Field value.

    • back optional array

      Passbook back fields.

      • key required string

        Field key.

      • label required string

        Field label.

      • value required string

        Field value.

  • general object

    General information.

    • description required string

      Passbook description.

    • transit_type required for passbook type "boarding_pass" predefined string "air" , "boat", "train" , "bus" , "generic"

      Passbook transit_type.

    • logo_text required string

      Passbook logo_text.

    • expiration_date optional date

      Passbook expiration date.

    • lock_screen_title optional string

      Passbook lock screen text.

    • colors optional object

      Passbooks colors.

      • background optional string

        Passbook background color.

      • label optional string

        Passbook label color.

      • foreground optional string

        Passbook foreground color.

  • notifications optional object

    Passbook notifications.

    • date optional date

      Passbook notification date.

    • locations optional array

      Passbook notification locations.

      • place required string

        Location place.

      • latitude required numeric

        Location place latitude.

      • longitude required numeric

        Location place longitude.

Response

If the request succeeds, an object with the passbook id is returned. Returns an error on failure.

Object Attributes
  • id numeric

    The id of created passbook.

/passbooks

POST https://[HOST]/apis/coupon/v1/passbooks
POST https://[HOST]/apis/coupon/v1/passbooks
Content-Type : application/json
{
	 "type" : "event_ticket",
	 "images" : {
          "icon" : "ca1cfb80b12b411033aa30ea2199af25",
          "logo" : "ca1cfb80b12b4112a30ea2199afaa",
          "thumbnail" : "ca1cfb80b1845a1033aa30ea2199afca"
      },
      "fields" : {
          "header" : [
              {
                  "key" : "HCE",
                  "label" : "Event",
                  "value" : "LC"
              }
          ],
          "primary" : [
              {
                  "key" : "HETNM",
                  "label" : "Event name",
                  "value" : "Pink Floyd in USA"
              }
          ],
          "secondary" : [
              {
                  "key" : "HCEATND",
                  "label" : "Attendee",
                  "value" : "John Smith"
              }
          ],
          "auxiliary" : [
              {
                  "key" : "HCELOC",
                  "label" : "Location",
                  "value" : "Florida, Miami, USA"
              }
          ],
          "back" : [
              {
                  "key" : "DESC",
                  "label" : "Description",
                  "value" : "Pink Floyd last concert for 2015"
              }
          ],
      },
      "general" : {
          "description" : "Concert event ticket",
          "logo_text" : "My concert",
          "expiration_date" : "2015-12-12 11:00:00",
          "lock_screen_title" : "Live concert ticket",
          "colors" : {
              "background" : "#ffffff",
              "label" : "#000000",
              "foreground" : "#000000"
          }
      },
      "notifications" : {
          "date" : "2015-12-12 09:00:00",
          "locations" : [
              {
                  "place" : "Miami",
                  "latitude" : "25.7738889",
                  "longitude" : "-80.1938889"
              }
          ]
      }
}
{
	 "status_code" : 201,
	 "status_message" : "Created",
	 "payload" : {
	 	 "id" : 1098
	 }
}

The PASSBOOKS/{ID} Request

GET

The passbooks GET request is used to get a passbook.

URL Parameters
  • id required numeric

    The id of passbook.

Response

If the request succeeds, a passbook object is returned. Returns an error on failure.

Object Attributes
  • type predefined string "boarding_pass" , "coupon", "event_ticket" , "generic" , "store_card"

    The type of passbook.

  • images object

    images of passbooks.

    • icon object

      icon image of passbook.

      • non_retina_uri string

        Non retina icon image

      • retina_uri string

        Retina icon image

    • logo object

      logo image of passbook.

      • non_retina_uri string

        Non retina logo image

      • retina_uri string

        Retina logo image

    • background object

      background image of passbook.

      • non_retina_uri string

        Non retina background image

      • retina_uri string

        Retina background image

    • footer object

      footer image of passbook.

      • non_retina_uri string

        Non retina footer image

      • retina_uri string

        Retina footer image

    • strip object

      strip image of passbook.

      • non_retina_uri string

        Non retina strip image

      • retina_uri string

        Retina strip image

    • thumbnail string

      thumbnail image of passbook.

      • non_retina_uri string

        Non retina thumbnail image

      • retina_uri string

        Retina thumbnail image

  • fields object

    fields of passbook.

    • header array

      Passbook header fields.

      • key string

        Field key.

      • label string

        Field label.

      • value string

        Field value.

    • primary array

      Passbook primary fields.

      • key string

        Field key.

      • label string

        Field label.

      • value string

        Field value.

    • secondary array

      Passbook secondary fields.

      • key string

        Field key.

      • label string

        Field label.

      • value string

        Field value.

    • auxiliary array

      Passbook auxiliary fields.

      • key string

        Field key.

      • label string

        Field label.

      • value string

        Field value.

    • back array

      Passbook back fields.

      • key string

        Field key.

      • label string

        Field label.

      • value string

        Field value.

  • general object

    General information.

    • description string

      Passbook description.

    • transit_type predefined string "air" , "boat", "train" , "bus" , "generic"

      Passbook transit_type.

    • logo_text string

      Passbook logo text.

    • expiration_date date

      Passbook expiration date.

    • lock_screen_title string

      Passbook lock screen text.

    • colors object

      Passbook colors.

      • background string

        Passbook background color.

      • label string

        Passbook label color.

      • foreground string

        Passbook foreground color.

  • notifications object

    Passbook notifications.

    • date date

      Passbook notification date.

    • locations array

      Passbook notification locations.

      • place string

        Location place.

      • latitude numeric

        Location latitude.

      • longitude numeric

        Location longitude.

/passbooks/{id}

GET https://[HOST]/apis/coupon/v1/passbooks/{id}
GET https://[HOST]/apis/coupon/v1/passbooks/1098
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 	 "type" : "event_ticket",
         "images" : {
              "icon" : {
                  "non_retina_uri" : "https://[HOST]/apis/coupon/v1/download/
                  a3074d8a3c3c187a3978e7a2b5a725b",
                  "retina_uri" : "https://[HOST]/apis/coupon/v1/download/e5f3d60801f86bc637ee8c4f3336c8ce"
              },
              "logo" : {
                  "non_retina_uri" : "https://[HOST]/apis/coupon/v1/download/
                  14ba932f0d0895bf0dcce6be37e211ae5",
                  "retina_uri" : "https://[HOST]/apis/coupon/v1/download/39b7aa0f252540b9ed0538d11f22e0f3"
              },
              "thumbnail" : {
                  "non_retina_uri" : "https://[HOST]/apis/coupon/v1/download/
                  2a3074843c3c85a33978e712b5a725b",
                  "retina_uri" : "https://[HOST]/apis/coupon/v1/download/e5f3d60801f33bc637ee8c4f3336c97c"
              }
           },
           "fields" : {
                "header" : [
                    {
                        "key" : "HCE",
                        "label" : "Event",
                        "value" : "LC"
                    }
                ],
                "primary" : [
                    {
                        "key" : "HETNM",
                        "label" : "Event name",
                        "value" : "Pink Floyd in USA"
                    }
                ],
                "secondary" : [
                    {
                        "key" : "HCEATND",
                        "label" : "Attendee",
                        "value" : "John Smith"
                    }
                ],
                "auxiliary" : [
                    {
                        "key" : "HCELOC",
                        "label" : "Location",
                        "value" : "Florida, Miami, USA"
                    }
                ],
                "back" : [
                    {
                        "key" : "DESC",
                        "label" : "Description",
                        "value" : "Pink Floyd last concert for 2015"
                    }
                ],
           },
           "general" : {
              "description" : "Concert event ticket",
              "logo_text" : "My concert",
              "expiration_date" : "2015-12-12 11:00:00",
              "lock_screen_title" : "Live concert ticket",
              "colors" : {
                  "background" : "#ffffff",
                  "label" : "#000000",
                  "foreground" : "#000000"
              }
           },
           "notifications" : {
              "date" : "2015-12-12 09:00:00",
              "locations" : [
                  {
                      "place" : "Miami",
                      "latitude" : "25.7738889",
                      "longitude" : "-80.1938889"
                  }
              ]
           }
	 }
}

The PASSBOOKS Request

DELETE

The passbooks DELETE request is used to delete a passbook.

URL Parameters
  • id required numeric

    The id of passbook.

Response

If the request succeeds, a response object with http status code 200 is returned. Returns an error on failure.

/passbooks/{id}

DELETE https://[HOST]/apis/coupon/v1/passbooks/{id}
DELETE https://[HOST]/apis/coupon/v1/passbooks/1078
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : ""
}

The REDEEM Request

POST

The /redeem POST request is used to validate and redeem coupons.

URL Parameters
  • redemption_api_key required string

    The api key provided by your single_coupon or broadcast request.

  • code required string

    The coupon code to be redeemed.

Response

If the request succeeded, an object is returned, which includes the result of the redemption attempt. Otherwise, an error is returned.

Redeem Code

POST https://coupon/apis/v1/redeem/{redemption_api_key}/{code}
POST https://coupon/apis/v1/redeem/{das9dj320ej39rj29rj3b4htlk54324243djasd3232r4tu5u}/{DFE7879632213TYWW435345}
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
	 }
}