Code API - Request codes to issue to consumers
The Uniqodo Distributor APIs provides code publishing distributors with a way of building Uniqodo codes in their website or application. Every distributor is set up with an API key providing access to two different RESTful APIs, the Offer API and the Code API.
This documentation explains the Code API, which provides the actual unique codes for publisher distributors to give to customers. When a distributor wishes to give a code to a customer, they use this API to request a code live.
The Offer API provides publishing distributors with a full list of the code triggered offers that merchants have given them permission to promote. The Offer API doesn’t provide the actual codes to provide to customers, but only the information about the offer or discount. The Offer API is documented here.
The Code API (RESTful)
End Point
http://api.uniqodo.com/code/API_KEY/OFFERID?uid=CUSTOMER_UNIQUE_IDENTIFIER
Example GET Request
- Offer ID: 1234
- Test API Key: $s1321se}2116c702c6989223420f4ddde4e19da4016b2f9f54c
https://api.uniqodo.com/code/$s1321se}2116c702c6989223420f4ddde4e19da4016b2f9f54c/1234
Parameters
Values | Description | Required |
API_KEY | The API key assigned to your distributor account. | Yes |
OFFERID | The unique identifier for the merchant offer that the distributor is requesting a code for. | Yes |
UID | Customer's unique identifier. | No |
Customer Identifier Example
https://api.uniqodo.com/code/6c702c6989223420f4ddde4e19da4016b2f9f54c/1234?uid=example@email.com
Parameter | Description | Required |
uid | The customer's unique identifier like an email address or ID, if available. Allows unique codes to be linked to a customers identity. Please note that if this parameter is supplied, the rule for deciding the number of unique codes allowed per customer, as defined by the merchant, will be triggered. The default behaviour is to issue one unique code per customer per promotion i.e. the same unique code will be issued for the same customer email/identifier for a given promotion. This is mandatory for Secure Code promotions where a customer must proof their identity by supplying the same unique identifier used to generate the code. | No |
Response
The response format is JSON. There are two important properties to look for- the data key contains the details of the code and the errors key contains an array of all errors if the code request is not successful. The data key is empty when no code has been generated due to an error.
{
"data": {
"offerId": 352,
"code": "E7WZ86TH7",
"endDate": "2033-12-01T23:59:00+0000",
"url": "http:\/\/www.uniqodo.com?uqd=E7WZ86TH7",
"merchantId": 1,
"discount": null,
"availableToRedeem": 1220
},
"errors": []
}Item | Description | Example |
offerId | The unique identifier for each merchant offer. | 451 |
code | The generated unique code to be supplied to the customer . | JD46BK |
endDate | The date and time the offer expires. If the promotion has dynamic expiry dates this will be passed. | 2015-06-30T23:59:00+0100 |
merchantId | The unique identifier for the merchant. | 1 |
url | The URL of the page on the merchant’s site where traffic should be directed to. The distributor should prefix any required tracking redirects. | |
discount | The promotion discount details if available, discount_amount - Value of the discount applied to this code | { |
availableToRedeem | The number of codes that are left to be redeemed for this offer. | 998 |
Errors
The response errors key contains an array of all errors if the code request is not successful or an empty array if there are no errors. Each error contained in the array has a code and a corresponding message describing the error. Some sample error messages structure are shown below.
{
"data": {},
"errors": [{
"code": 207,
"message": "This code is currently inactive."
}]
}{
"data": {},
"errors": [{
"code": 206,
"message": "This code has been expired because a limit has been reached."
}]
}{
"data": {},
"errors": [{
"code": 101,
"message": "Invalid API key supplied"
}]
}
{
"data": {},
"errors": [{
"code": 202,
"message": "This code has expired and can no longer be used."
}]
}Error Code | Message | Reason |
101 | Invalid API key supplied. | The API key supplied in the request in not valid. |
304 | Promotion not accessible. | The promotion does not existing in the list of promotion you have been granted access to promote. |
400 | The request could not be completed- check that parameters are correct. | One of the required parameters may be missing or the URL is badly formed. |
206 | This promotion has been expired because a limit has been reached. | The code limit set for this promotion has been reached. |
202 | This promotion has expired and can no longer be used. | Promotion expiry date has been reached. |
207 | This promotion is currently inactive. | The promotion has not yet started or it has been deactivated. |
208 | An email address or a unique identifier is required to use this code. | The promotion requires a unique user identifier so that the code can be secured against the user identifier. |
