Core API

Introduction

Basic API design considerations:

Overview

OneGo Core API shares it's design with other popular APIs currently available. Authentication is based on subset of OAuth 2, calls to endpoints are handled using simple GET, POST requests and returned data format is JSON. Note that request parameters in most cases are not JSON, but instead simple HTTP key/value pairs.

Requests

Request format is dictated by exact resource, but mostly HTTP key/value pairs with some exceptions of JSON passed via http POST/PUT; Requests must be augmented with authentication headers for resources that do not have anonymous access.

Responses

In case of successful request, responses will look like:

{
    "merchants" : [ {
    "status" : "ACTIVE",
    "title" : "At Martha's",
    "imageUris" : {
      "45x45": "http://static.onego.com/../common/images/default/merchant-45x45.png",
      "110x110": "http://static.onego.com/../common/images/default/merchant-110x110.png",
      "200x200": "http://static.onego.com/../common/images/default/merchant-200x200.png",
      "300x300": "http://static.onego.com/../common/images/default/merchant-300x300.png"
    }
    "unreadBenefitCount" : 0,
    "isFriend" : false,
    "prepaidEnabled" : true,
    "actionUris" : {
        "CONNECT" : "/services/v1/merchants/rk04bgi64t6o02276wbeeq5vuzylsjybpy8u/connect",
        "INBOX" : "/services/v1/merchants/rk04bgi64t6o0j576wbeeq5guzylsjybpy8u/inbox"
    }, {
    "status" : "ACTIVE",
    "title" : "BigCity Electronics",
    "imageUris" : {
      "45x45": "http://static.onego.com/../common/images/default/merchant-45x45.png",
      "110x110": "http://static.onego.com/../common/images/default/merchant-110x110.png",
      "200x200": "http://static.onego.com/../common/images/default/merchant-200x200.png",
      "300x300": "http://static.onego.com/../common/images/default/merchant-300x300.png"
    }
    "unreadMessageCount" : 0,
    "isFriend" : false,
    ...
}

API is designed to be navigable by returning related resources, or actions that can be executed on returned resources. Relative resources/actions are returned in resourceActionUris. This list might vary on resource state.

Versioning

Currently API changes will be implemented in backward-forward compatible way, where major changes will result in API base uri change (/v1/, /v2/, etc.).

Errors

Appropriate HTTP status codes are used to indicate base problems, where in addition JSON error structure is returned where additional information is available:

{
    "error":"internal_error",
    "error_description":"Woops."
}

Error codes:

HTTP Status Error code Explanation
500 "internal_error" Some unexpected condition occurred.
400 "invalid_request" Required parameters are not provided or do not match required format, or provided Json is malformed.
401 "invalid_token" Access token is invalid, expired, etc.
401 "unauthorized" Either invalid authorization scheme was used, or no authorization headers provided for resource where authorization is mandatory.
403 "not_found" Requested object does not exist.

Mobile application and authentication portal interaction

OneGo authentication portal is implemented in accordance to OAuth 2.0 with extensions for custom flows (password reset, account registration) that are not covered by OAuth spec.

Application supports following features:

  • Sign-in via OneGo ID, FB, Google;
  • Create OneGo account;
  • Reset OneGo password;

This document describes basic flows and puts emphasis on client/server interaction points.

Client sign-up

Currently sign-up (obtaining client access key/secret) is a manual process and has to be handled manually with OneGo API developers. Write email to support@onego.com and we will be more than happy to issue a new access key for you.

Login flow

Clicking on Login button opens webview with url:

https://auth.onego.com/m/authorize?client_id={clientId}&response_type=token

Authentication form enables user to login using her preferred method (OneGo, Facebook, Google) or to reset OneGo account password. Client application must listen for 302 redirects which serve as interaction points. Only redirects to one of: /m/success, /m/error or /m/end must be handled by client applications.

OAuth request parameters

OAuth specification defines set of query parameters that any OAuth endpoint MUST support. Following OAuth query parameters are supported by /m/authorize endpoint:

Parameter Description
response_type REQUIRED. Must be set to token.
client_id REQUIRED. Provided unique identifier for client, that is required to be 36 symbols [a-Z0-9] and is obtained during Sign-up
redirect_uri NOT USED. redirect_uri is agreed upon in advance and upon successful authentication API redirects to https://auth.onego.com/m/success.
scope NOT USED.

Non-OAuth request parameters

https://auth.onego.com/m/authorize accepts additional request parameters not defined by OAuth:

Parameter Description
email Used to pre-fill login form email/username field. This parameter is provided for convienience and is used in some flows (password reset, account creation). Value must conform to http://tools.ietf.org/html/rfc5322 and http://tools.ietf.org/html/rfc5321.
lang Used for setting UI language for sign-in form; Valid values are 'en' and 'lt'. When not provided defaults to 'en'.

None of these parameters are mandatory, but when provided they are validated. In case of validation errors error page is displayed (not usual OAuth redirect to /m/error), but instead HTTP 400 is returned with details on error in the page. HTTP 400 indicates that this is configuration error - parameters invalid, so configuration has to be checked.

Request:

https://auth.onego.com/m/authorize?
    client_id=CLIENT_ID&
    response_type=token&
    lang=en&
    email=zozo@not.found

Opened application allows user to perform different actions (sign-in, sign-up, reset password, etc.) and informs client via redirects to /m/success or /m/error endpoints.

Successful Authentication - redirect to /m/success

User enters her login credentials, and upon successful authentication 302 redirect is issued to https://auth.onego.com/m/success endpoint. Authentication parameter format is in accordance with OAuth 2 "Implicit grant", "Access Token Response" specification. See http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.2 for details.

Non-OAuth response parameters

Parameter Description
account-created True or false. In some cases (3rd party login) under the hood account is being created, in this case response will include additional parameter set to 'account-created=true'. In this case BIM management view must be displayed.

Example response is:

 https://auth.onego.com/m/success
      #access_token=FJQbwq9
      &token_type=bearer
      &expires_in=3600

Failed authentication - redirect to /m/error

When one of the following occurs:

  • Request parameters to https://auth.onego.com/m/authorize are invalid, or client_id is not registered/blocked;
  • Internal server error (ah snap);
  • User account is blocked;
  • Bad login/password entered;
  • Limit of login tries is exceeded (bad login/password);
  • Invalid values were provided by user, but this is not standard OAuth way, so different error code and additional parameters are returned.

302 redirect is issued to https://auth.onego.com/m/error endpoint. Authentication parameter format is in accordance with OAuth 2 "Implicit grant", "Error response" specification. See http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.2 for details.

Example response is:

 https://auth.onego.com/m/error
      #error=invalid_request
      &error_description=Parameter+client_id+is+missing
Unrecoverable error response

These are mainly OAuth error responses due to implementation or configuration errors. When one of these error codes are emitted, error message should be displayed and user returned to main application screen.

Available unrecoverable error codes - where client application should display generic error message with try later and display custom view, as web application will not contain any meaningful content:

Error Code Description
invalid_request Required request parameter was not provided.
unsupported_response_type Other that response_type='token' was provided.
unauthorized_client Provided 'client_id' is of correct format, but is not present or blocked.
server_error Ok, should work later.
temporarily_unavailable Supposedly server is being restarted or some other maintenance work performed.

In case of these errors generic error message should be displayed to end-user.

Recoverable error codes

These are in part OAuth error responses, in part extensions to handle input validation errors. As auth portal is designed to employ native means to provide feedback on errors for end-user, so even recoverable errors are emitted as error redirects which MUST be intercepted by client application and presented in a native fashion according to target platforms UI design guidelines.

Error response is emitted with additional response parameters: message - nice message that can be displayed to end-user, is set in same language as application UI.

Available recoverable error codes - where application MUST display error message and stay in web view and allow user to keep entering username/password:

Error Code Description
access_denied Either user triggered max login attempt throttling guard, or account is blocked - unaccessible.
user_error User entered incorrect values (email format, password format, age requirements not met, etc.).

In case of these errors native popup should be displayed with text from message response parameter and redirect should not be followed (application state left on same form).

Cancel action error codes

These error codes are emitted once user intentionally rejects some action (third party sign-in grant rejected, etc.). In this case no error is displayed to end-user but instead application should exit from current view and open main app view.

Available recoverable error codes - where application MUST display error message and stay in web view and allow user to keep entering username/password:

Error Code Description
action_cancelled User rejected facebook/google OAuth grant.
Unspecified error codes

If application receives unspecified error code, generic error message should be displayed and user returned to main applicaiton screen.

Other outcome - redirect to /m/end

This is the case, when neither user authenticated, nor some error occured - for example user, instead of authentication flow proceeded to password reset or some other flow presented via web application that does not result in any of expected and documented by OAuth outcomes.

In this case client application should display the message provided via 'title' and 'message' parameter to user via modal window and after closing this window close webview and display 'Dashboard' view.

Example response is:

 https://auth.onego.com/m/end
      #title=Success!
      #message=An+email+with+instructions+on+how+to+recover+your+password+were+sent+to+qwe@qwe.com

Register flow

Clicking on Register button opens webview with url: https://auth.onego.com/m/register?client_id={clientId}. Authentication form enables user to create account using preffered method (OneGo, Facebook, Google). In any of the following client application must listen for 302 redirects which serve as interaction points. Redirects can be issued to one of: /m/success, /m/error or /m/end.

Note that no-matter that this is not Login flow, it can result in actual authentication, so /m/success and /m/error redirects MUST be handled in same way as in Login flow.

Register flow onego://register/end

Registration flow results in account creation, confirmation, etc. so application must register for onego://register/end uri handling that are requested from different aplications (safari, mail client).

When application receives onego://register it must open /m/autorize as in Login flow where possible query parameters might be:

Parameter Description
email Used to pre-fill login form email/username field.

Example request is:

 onego://register/end
      ?email=qwe@example.org

Password reset flow onego://password/reset/end

Password reset flow results in receiving password reset intent email, filling in new password, etc. so application must register for onego://password/reset/end uri handling that are requested from different aplications (safari, mail client).

When application receives onego://password/reset/end it must open /m/autorize as in Login flow where possible query parameters might be:

Parameter Description
email Used to pre-fill login form email/username field.

Example request is:

 onego://password/reset/end
      ?email=qwe@example.org

Sign-out

Sign-out is a process of revoking earlier issued and valid Access Token. For revoking current user session Http POST https://auth.onego.com/m/logout endpoint must be issued with request parameters:

Parameter Description
client_id Provided unique identifier, that is required to be 36 symbols [a-Z0-9];
access_token Earlier issued access token via https://auth.onego.com/m/authorize endpoint.
 https://auth.onego.com/m/logout
      ?client_id=CLIENT_ID
      &access_token=ACCESS_TOKEN

In case of successful revocation, HTTP 200 OK is returned, otherwise https://auth.onego.com/m/error is issued. Revocation of invalid/expired access token is treated as an error case.

Error code/message mappings

access_denied

Language Message
en Provided account is not yet activated or is blocked due to security reasons. Please refer to FAQ for information.
lt Paskyra dar neaktyvuota arba užblokuota dėl saugumo. Daugiau informacijos rasite DUK'e.

generic error

Language Message
en Service is temporarily unavailable. Please try later.

/me resource

/me base resource is a placeholder for user profile related operations.

Endpoint URI Authentication
GET /me https://api.onego.com/services/v1/me Required
POST /me https://api.onego.com/services/v1/me Required
POST /me/photo https://api.onego.com/services/v1/me/photo Required

GET /me

Returns profile information for currently signed-in user.

Request

None.

Response

Buyer response

Field Description
firstName Buyer's first name.
middleName Buyer's middle name.
lastName Buyer's last name.
gender Any of UNKNOWN, FEMALE, MALE.
birthDate Format: number of milliseconds since January 1st 1970 UTC.
address A Location response object, if present.
pictureUris List of URIs to user profile picture. In case user did not specify explicit image (did not upload), default static image URI will be provided. In case user has external picture URL (i.e. facebook profile), only original size will be provided. See Image URIs for more details.
uiLanguage Returns buyer UI language code. Any of 'EN', 'LT'.
Action Description
PROFILE_EDIT POST /me to update user profile fields.
IMAGE_EDIT POST /me/photo to update user profile image.

Location response

Field Description
countryCode 'ISO 3166-1 alpha-2' country code.
countryName Country name.
stateCode 'ISO_3166-2' subdivision/state codes.
stateName State name.
cityName City name.
countyName County to which city belongs.
postalCode Postal code.
address Free-form address line.

Example

To retrieve currently signed-in user profile you need to have a valid 'AUTH_TOKEN' and to issue a command:

curl --get \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    https://api.onego.com/services/v1/me

Example response:

{
  "firstName" : "Jimmy",
  "middleName" : "",
  "lastName" : "Doe",
  "gender" : "MALE",
  "address" : {
      "address" : "1234 Sunrise Boulevard",
      "countryCode" : "US",
      "countryName" : "United States of America",
      "cityName" : "Beverly Hills",
      "countyName" : "Los Angeles"
  },
  "pictureUris" : {
      "45x45": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/small.jpeg?v=7",
      "110x110": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/large.jpeg?v=7",
      "200x200": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/larger.jpeg?v=7",
      "300x300": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/huge.jpeg?v=7"
  },
  "actionUris" : {
      "IMAGE_EDIT" : "/services/v1/me/photo",
      "PROFILE_EDIT" : "/services/v1/me"
  }
}

POST /me

Updates user profile. Supports partial update - when some field is not provided, or provided as null, it is left intact. To clear some value in user profile empty string must be provided.

Request

User request

Field Description
firstName Buyer's first name.
middleName Buyer's middle name.
lastName Buyers last name.
gender Any of UNKNOWN, FEMALE, MALE.
birthDate Format: ISO 8601, cannot be erased. Validates for user would be at least 14 years old.
address A Location request object. If set to null, address will be left intact.
uiLanguage Set buyer UI language. Any of 'en', 'lt'.

Location request

Field Description
countryCode 'ISO 3166-1 alpha-2' country code.
stateCode Valid state for provided country. 'state', 'city' input is enabled only for countries listed in GET /location/supported_countries resource. 'state' input is supported only for countries listed in GET /location/supported_states resource.
cityName Valid city for provided country in original language, cannot be set if 'country' is empty/null.
countyName Valid county, coupled with city. Used for picking correct city, if several cities exist in same 'country'/'state'.
postalCode Postal code. Free-form.
address Free-form address line.

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

To update user firstName field:

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    --data '{"firstName" : "Jimmy"}' \
    https://api.onego.com/services/v1/me

To clear user lastName field:

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    --data '{"lastName" : ""}' \
    https://api.onego.com/services/v1/me

Post address change:

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    --data '{"firstName" : "Jimmy", "address":{"address":"1235 Sunrise Boulevard","countryCode":"US",
          "cityName":"Beverly Hills","stateCode":null,"countyName":null,"postalCode":null}}' \
    https://api.onego.com/services/v1/me

POST /me/photo

Updates user profile image. Image size should not be smaller than 110x110 and not larger than 2 Megabytes in size.

Request

Accepts 'image/*' media type. Accepts 'multipart/form-data' media type.

Response

200 OK on successful update, or HTTP error response.

Examples

curl -XPOST --header "Accept: application/json" \
    --header "Content-Type: image/jpeg" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    --data-binary "@IMAGE_FILE" https://api.onego.com/services/v1/me/photo


curl -XPOST -F "image=@IMAGE_FILE" \
    --header "Content-type: multipart/form-data" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    https://api.onego.com/services/v1/me/photo

/notifications resource

/notifications base resource is a placeholder for notifications - iOS, email, etc.

Endpoint URI Authentication
PUT /notifications/ios/device/{deviceToken} https://api.onego.com/services/v1/notifications/ios/device/{deviceToken} Required
DELETE /notifications/ios/device/{deviceToken} https://api.onego.com/services/v1/notifications/ios/device/{deviceToken} Required
POST /notifications/ios/push/{mode}/{deviceToken}/{badge} https://api.onego.com/services/v1/notifications/ios/push/{mode}/{deviceToken}/{badge} Required
GET /notifications/email/{merchantId}/{hashCode} https://api.onego.com/services/v1/notifications/email/{merchantId}/{hashCode} Optional
PUT /notifications/email/{merchantId}/{hashCode} https://api.onego.com/services/v1/notifications/email/{merchantId}/{hashCode} Optional
GET /notifications/email/{merchantId} https://api.onego.com/services/v1/notifications/email/{merchantId} Required
PUT /notifications/email/{merchantId} https://api.onego.com/services/v1/notifications/email/{merchantId} Required

PUT notifications/ios/device/{deviceToken}

Registers device for iOS push notifications. Endpoint should be called either when user signs-in and push notifications are already enabled, or when push notifications are enabled for already authenticated user.

Note: currently only single 'deviceToken' is allowed for a single authenticated user - registering different device token, than existing will simply overwrite it.

Request

Type Field Description
Path param deviceToken Hexadecimal 64 character long APNS device token.

Response

200 OK when device was registered succesfully, or 400 - bad request in case device was already registered.

Example

To register device:

curl -X PUT \
    --header "Accept: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    https://api.onego.com/services/v1/notifications/ios/device/235235

DELETE notifications/ios/device/{deviceToken}

Deregister device from push notifications. Endpoint should be accessed:

  • When Application is being uninstalled;
  • When User signs-out.

Request

Type Field Description
Path param deviceToken Hexadecimal 64 character long APNS device token.

Response

200 OK on successful update, or HTTP error response with corresponding JSON. Deregistering not registered device token will emit 400 bad request response.

Example

To deregister a device:

curl -X DELETE \
    --header "Accept: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    https://api.onego.com/services/v1/notifications/ios/device/235235

POST notifications/ios/push/{mode}/{deviceToken}/{badge}

Send iOS push notification (badge) to device identified by 'deviceToken'.

Note: Endpoint is intended only for testing purposes.

Request

Type Field Description
Path param mode 'adhoc' when testing on released app version or 'dev' when testing while developing.
Path param deviceToken Hexadecimal 64 character long APNS device token.
Path param badge Badge value to push - integer value.

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

Short description:

curl -X POST --header "Accept: application/json" \
    --header "Authorization: Bearer AUTH_TOKEN" \
    https://api.onego.com/services/v1/notifications/ios/push/dev/3245345/2

GET notifications/email/{merchantId}/{hashCode}

Get email notifications periodicity. Used when buyer is not authenticated. We send hash code in every notification email.

Request

Type Field Description
Path param merchantId Id of connected merchant.
Path param hashCode Unique hash code which is inluded in every notification email.

Response

Field Description
periodicity Periodicity

Example

Request

curl --get \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  https://api.onego.com/services/v1/notifications/email/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/ppqr1ekcnx3z0jok4oveh40nx3z0jofcw9f

Response

{
  "periodicity" : "NEVER"
}

PUT notifications/email/{merchantId}/{hashCode}

Set email notifications periodicity. Used when buyer is not authenticated. We send hash code in every notification email.

Request

Type Field Description
Path param merchantId Id of connected merchant.
Path param hashCode Unique hash code which is inluded in every notification email.
Data periodicity Periodicity

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

curl -X PUT  \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"periodicity":"IMMEDIATELY"}' \
  https://api.onego.com/services/v1/notifications/email/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/ppqr1ekcnx3z0jok4oveh40nx3z0jofcw9f

GET notifications/email/{merchantId}

Get email notifications periodicity.

Request

Type Field Description
Path param merchantId Id of connected merchant.

Response

Field Description
periodicity Periodicity

Example

Request

curl --get \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  https://api.onego.com/services/v1/notifications/email/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

Response

{
  "periodicity" : "NEVER"
}

PUT notifications/email/{merchantId}

Set email notifications periodicity.

Request

Type Field Description
Path param merchantId Id of connected merchant.
Data periodicity Periodicity

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

curl -X PUT  \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ACCESS_TOKEN" \
  --data '{"periodicity":"IMMEDIATELY"}' \
  https://api.onego.com/services/v1/notifications/email/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

/merchants resource

/merchants base resource is a placeholder for merchant related operations.

Endpoint URI Authentication
GET /merchants https://api.onego.com/services/v1/merchants Required
GET /merchants/{id}/stores https://api.onego.com/services/v1/merchants/{id}/stores Optional
GET /merchants/{id}/inbox https://api.onego.com/services/v1/merchants/{id}/inbox Optional
POST /merchants/{id}/connect https://api.onego.com/services/v1/merchants/{id}/connect Required
POST /merchants/{id}/disconnect https://api.onego.com/services/v1/merchants/{id}/disconnect Required

GET /merchants

Returns a list of merchants to which the buyer is connected.

Request

None.

Response

Field Description
merchants A list of Merchant item items.

Example

Request:

curl --get \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/merchants

Response:

{
  "merchants" : [ {
    "status" : "ACTIVE",
    "title" : "Tom's Cookies'n'Pies",
    "prepaid" : {
      "currentBalance" : "0.00",
      "futureBalance" : "0.00"
    },
    "activeBenefitCount" : 3,
    "unreadBenefitCount" : 0,
    "imageUris" : {
      "45x45": "https://onego-img.s3.amazonaws.com/merchant/uoaoyi2vgzlv/small.jpeg?v=1",
      "110x110": "https://onego-img.s3.amazonaws.com/merchant/uoaoyi2vgzlv/large.jpeg?v=1",
      "200x200": "https://onego-img.s3.amazonaws.com/merchant/uoaoyi2vgzlv/larger.jpeg?v=1",
      "300x300": "https://onego-img.s3.amazonaws.com/merchant/uoaoyi2vgzlv/huge.jpeg?v=1"
    },
    "isFriend" : true,
    "prepaidEnabled" : true,
    "actionUris" : {
      "INBOX" : "/services/v1/merchants/qfwh2gkh3155gnzxd4sfbwtouoaoyi2vgzlv/inbox"
    }
  }, {
    "status" : "ACTIVE",
    "title" : "Martha's Snacks-to-go",
    "prepaid" : {
      "currentBalance" : "0.00",
      "futureBalance" : "0.00"
    },
    "activeBenefitCount" : 4,
    "unreadBenefitCount" : 3,
    "imageUris" : {
      "45x45": "http://static.onego.com/common/images/default/merchant-45x45.png",
      "110x110": "http://static.test.onego.com/common/images/default/merchant-110x110.png",
      "200x200": "http://static.test.onego.com/common/images/default/merchant-200x200.png",
      "300x300": "http://static.test.onego.com/common/images/default/merchant-300x300.png"
    }
    "isFriend" : true,
    "prepaidEnabled" : true,
    "actionUris" : {
      "INBOX" : "/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/inbox"
    }
  }, {
    "status" : "ACTIVE",
    "title" : "Vince's Bikeparts",
    "activeBenefitCount" : 0,
    "unreadBenefitCount" : 0,
    "imageUris" : {
      "45x45": "http://static.onego.com/common/images/default/merchant-45x45.png",
      "110x110": "http://static.onego.com/common/images/default/merchant-110x110.png",
      "200x200": "http://static.onego.com/common/images/default/merchant-200x200.png",
      "300x300": "http://static.onego.com/common/images/default/merchant-300x300.png"
    }
    "isFriend" : true,
    "prepaidEnabled" : true,
    "actionUris" : {
      "INBOX" : "/services/v1/merchants/4v7j9gc15c7mi3v3w8yr4k57esgnjrmhgmu7/inbox"
    }
  } ]
}

GET /merchants/{id}/inbox

Retrieve buyer offer and fund balance for provided merchant. For authenticated buyer her benefits are returned with current fund (prepaid) amounts and statuses, when for unauthenticated public merchants benefits/offers are returned without any fund balances.

Request

Type Name Description Constraints
URI {id} Unique merchant identifier. Required

Response

Field Description
merchant Merchant item
benefits A list of Benefit items

Example

Authenticated request:

curl --get \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/merchants/4v7j9gc15c7mi3v3w8yr4k57esgnjrmhgmu7/inbox

Example response:

{
  "merchant" : {
      "status" : "ACTIVE",
      "title" : "Vince's Bikeparts",
      "prepaid" : {
        "currentBalance" : "0.00",
        "futureBalance" : "0.00"
      },
      "activeBenefitCount" : 1,
      "unreadBenefitCount" : 1,
      "imageUris" : {
          "45x45": "http://static.onego.com/common/images/default/merchant-45x45.png",
          "110x110": "http://static.onego.com/common/images/default/merchant-110x110.png",
          "200x200": "http://static.onego.com/common/images/default/merchant-200x200.png",
          "300x300": "http://static.onego.com/common/images/default/merchant-300x300.png"
      }
      "isFriend" : true,
      "prepaidEnabled" : true,
      "actionUris" : {
          "INBOX" : "/services/v1/merchants/4v7j9gc15c7mi3v3w8yr4k57esgnjrmhgmu7/inbox"
      }
  },
  "benefits" : [ {
      "type" : "OFFER",
      "count" : 1,
      "description" : "10% off new bike tires - this month only!",
      "status" : "ACTIVE",
      "title" : "Get new tires for your bike at a good price",
      "flags" : [ "NOT_READ" ],
      "imageUris" : {
          "45x45": "http://static.onego.com/common/images/default/offer-45x45.png",
          "110x110": "http://static.onego.com/common/images/default/offer-110x110.png",
          "200x200": "http://static.onego.com/common/images/default/offer-200x200.png",
          "300x300": "http://static.onego.com/common/images/default/offer-300x300.png"
      }
      "contract" : "",
      "validUntil" : 1348931180000,
      "benefitUri" : "/services/v1/benefits/cofwseu8brk0df2shqu6y53ig8spsr",
      "actionUris" : {
          "MARK_VIEWED" : "/services/v1/benefits/cofwseu8brk0df2shqu6y53ig8spsr/view",
          "MARK_READ" : "/services/v1/benefits/cofwseu8brk0df2shqu6y53ig8spsr/read",
          "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/cofwseu8brk0df2shqu6y53ig8spsr"
      }
    }, {
      "type" : "PREPAID",
      "count" : 1,
      "description" : "g-Discount-hw74q-Description",
      "status" : "ACTIVE",
      "title" : "g-Discount-hw74q",
      "flags" : [ "NOT_READ" ],
      "imageUris" : {
          "45x45": "http://static.onego.com/common/images/default/percent-45x45.png",
          "110x110": "http://static.onego.com/common/images/default/percent-110x110.png",
          "200x200": "http://static.onego.com/common/images/default/percent-200x200.png",
          "300x300": "http://static.onego.com/common/images/default/percent-300x300.png"
      }
      "validUntil" : 1316525668000,
      "benefitUri" : "/services/v1/benefits/ppm7de6wj4qr1ekcnx3z0jok4oveh40fcw9fs1",
      "actionUris" : {
          "MARK_VIEWED" : "/services/v1/benefits/ppqr1ekcnx3z0jok4oveh40fcw9fs1/view",
          "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/ppqr1ekcnx3z0jok4oveh40fcw9fs1"
      }
  } ],
}

Unauthenticated request:

curl --get \
    --header "Accept: application/json" \
    https://api.onego.com/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/inbox

Example response:

{
    "merchant" : {
        "status" : "ACTIVE",
        "title" : "Tom's Cookies'n'Pies",
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/merchant-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/merchant-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/merchant-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/merchant-300x300.png"
        }
        "isFriend" : false,
        "prepaidEnabled" : true,
        "actionUris" : {
            "CONNECT" : "/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/connect",
            "INBOX" : "/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/inbox"
        }
    },
    "benefits" : [ {
        "type" : "OFFER",
        "count" : 1,
        "description" : "Blueberry pies are 10% cheaper - this month only.",
        "status" : "ELIGIBLE",
        "title" : "Your favorite blueberry pies are now cheaper!",
        "flags" : [ "NOT_READ" ],
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/offer-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/offer-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/offer-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/offer-300x300.png"
        }
        "contract" : "",
        "validUntil" : 1348931180000,
        "eligibility" : {
            "price" : 0,
            "needToBecomeFriend" : true,
            "addSharedBenefit" : false
        },
        "benefitUri" : "/services/v1/benefits/cofwseu8brk0df2shqu6y53ig8sp",
        "actionUris" : {
            "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/cofwseu8brk0df2shqu6y53ig8sp"
        }
      }, {
        "type" : "OFFER",
        "count" : 1,
        "description" : "Buy a cappuccino and get a cookie of your choice for free!",
        "status" : "ELIGIBLE",
        "title" : "Cappuccino likes company!",
        "flags" : [ "NOT_READ" ],
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/offer-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/offer-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/offer-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/offer-300x300.png"
        }
        "validUntil" : 1317390023000,
        "eligibility" : {
            "price" : 0,
            "needToBecomeFriend" : true,
            "addSharedBenefit" : false
        },
        "benefitUri" : "/services/v1/benefits/cocdwgk7f4zykxrn0gih1vyjwgfd",
        "actionUris" : {
            "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/cocdwgk7f4zykxrn0gih1vyjwgfd"
        }
      }, {
        "type" : "OFFER",
        "count" : 1,
        "description" : "Just until saturday a cup of coffee will cost you USD 0.99!",
        "status" : "ELIGIBLE",
        "title" : "Hurry up - grab a coffee for USD 0.99",
        "flags" : [ "NOT_READ" ],
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/offer-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/offer-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/offer-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/offer-300x300.png"
        }
        "validUntil" : 1317476031000,
        "eligibility" : {
            "price" : 0,
            "needToBecomeFriend" : true,
            "addSharedBenefit" : false
        },
        "benefitUri" : "/services/v1/benefits/co7nxziv02d7eaqc6bvs6bhho3vy",
        "actionUris" : {
            "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/co7nxziv02d7eaqc6bvs6bhho3vy"
        }
      }, {
        "type" : "OFFER",
        "count" : 1,
        "description" : "Buy a coffee and get a fresh croissant for just USD 0.99",
        "status" : "ELIGIBLE",
        "title" : "Start your day with some croissants!",
        "flags" : [ "NOT_READ" ],
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/offer-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/offer-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/offer-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/offer-300x300.png"
        }
        "contract" : "This offer is valid until 10AM, so hurry up!",
        "validUntil" : 1316769732000,
        "eligibility" : {
            "price" : 0,
            "needToBecomeFriend" : true,
            "addSharedBenefit" : false
        },
        "benefitUri" : "/services/v1/benefits/con61vn01b9kkk1ud53d2b2q7uwh",
        "actionUris" : {
            "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/con61vn01b9kkk1ud53d2b2q7uwh"
        }
      }, {
        "type" : "PREPAID",
        "count" : 1,
        "description" : "If you buy 3 cakes the third one will be free!",
        "status" : "ELIGIBLE",
        "title" : "Get 3 cakes for the price of 2",
        "flags" : [ "NOT_READ" ],
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/percent-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/percent-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/percent-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/percent-300x300.png"
        }
        "validUntil" : 1316525668000,
        "eligibility" : {
            "price" : 0,
            "needToBecomeFriend" : true,
            "addSharedBenefit" : false
        },
        "benefitUri" : "/services/v1/benefits/ppqr1ekcnx3z0jok4oveh40fcw9f",
        "actionUris" : {
            "VIEW_EXTERNAL" : "http://buyers.onego.com/benefit/ppqr1ekcnx3z0jok4oveh40fcw9f"
        }
      } ]
  }

POST /merchants/{id}/connect

Befriends current buyer and merchant, identified by provided uri. Operation is considered to be safe - either in case merchant and buyer is connected or not, Http Ok is returned - calling multiple times does not have any side effects.

Request

Type Name Description Constraints
URI {id} Unique merchant identifier. Required

Response

None.

Example

curl -X POST \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/connect

POST /merchants/{id}/disconnect

Disconnects current buyer from the merchant identified by provided uri. Operation is considered to be safe - either in case merchant and buyer is connected or not, Http Ok is returned - calling multiple times does not have any side effects.

Request

Type Name Description Constraints
URI {id} Unique merchant identifier. Required

Response

None.

Example

curl -X POST \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/disconnect

GET /merchants/{id}/stores

Retrieve all merchant stores information like address, working time, coordinates and other.

Request

Type Name Description Constraints
URI {id} Unique active merchant identifier. Required

Response

Field Description
stores A list of Store items.

Example

Authenticated request:

curl --get \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/merchants/wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe/stores

Response:

{
    "stores" : [ {
        "title" : "Tom's Cookies'n'Pies @ Gedimino 7",
        "description" : "Cheesy pies on funky plaza",
        "features" : [ "PARKING", "WIFI" ],
        "workingTime" : {
            "TUE" : {
                "starting" : "09:00:00",
                "ending" : "22:00:00"
            },
            "WED" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "THU" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "FRI" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "SAT" : {
                "starting" : "08:00:00",
                "ending" : "24:00:00"
            },
            "SUN" : {
                "starting" : "08:00:00",
                "ending" : "24:00:00"
            }
        },
        "phone" : "+1 (234) 456-7890",
        "address" : {
            "address" : "Gedimino str. 7, Vilnius, Lithuania",
            "cityName" : "Vilnius",
            "stateName" : ""
        },
        "coordinates" : {
            "latitude" : "54.696",
            "longitude" : "25.277"
        }
    }, {
        "title" : "Tom's Cookies'n'Pies @ Europa",
        "description" : "Break and taste our chocy cookies",
        "features" : [ "PARKING", "WIFI" ],
        "workingTime" : {
            "MON" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "TUE" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
             },
            "WED" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "THU" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "FRI" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "SAT" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            },
            "SUN" : {
                "starting" : "08:00:00",
                "ending" : "22:00:00"
            }
        },
        "phone" : "+1 (234) 456-7890",
        "address" : {
            "address" : "Konstitucijos pr. 7A, Vilnius, Lithuania",
            "cityName" : "Vilnius",
            "stateName" : ""
        }
        "coordinates" : {
            "latitude" : "54.696",
            "longitude" : "25.277"
        }
    } ]
}

/benefits resource

/benefits resource is used for getting info on benefits and performing actions: donating, marking benefits as viewed, read, etc.

Endpoint URI Authentication
GET /benefits/{benefitId} https://api.onego.com/services/v1/benefits/{benefitId} Optional
POST /benefits/{benefitId}/read https://api.onego.com/services/v1/benefits/{benefitId}/read Required
POST /benefits/{benefitId}/view https://api.onego.com/services/v1/benefits/{benefitId}/view Required
POST /benefits/{benefitId}/donate https://api.onego.com/services/v1/benefits/{benefitId}/donate Required
POST /benefits/{benefitId}/share https://api.onego.com/services/v1/benefits/{benefitId}/share Required

GET /benefits/{benefitId}

Returns the description of the benefit by the specified id.

Request

Type Name Description Constraints
URI {benefitId} Unique benefit identifier. Required

Response

Field Description
merchantId Unique merchant identifier.
benefit A single Benefit item.

Example

Authenticated request:

curl --get \
    --header "Accept: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

Response:

{
    "merchantId" : "wg2hqysagxoiqkc7tydbv8ckj4bbltutsxqe",
    "benefit" : {
        "type" : "OFFER",
        "count" : 0,
        "description" : "Buy a cappuccino and get a cookie of your choice for free!",
        "status" : "ACTIVE",
        "title" : "Cappuccino likes company",
        "flags" : [ "NOT_READ" ],
        "imageUris" : {
            "45x45": "http://static.onego.com/common/images/default/offer-45x45.png",
            "110x110": "http://static.onego.com/common/images/default/offer-110x110.png",
            "200x200": "http://static.onego.com/common/images/default/offer-200x200.png",
            "300x300": "http://static.onego.com/common/images/default/offer-300x300.png"
        }
        "contract" : "",
        "validUntil" : 1348931180000,
        "benefitUri" : "/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr",
        "actionUris" : {
            "MARK_VIEWED" : "/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/view",
            "MARK_READ" : "/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/read",
            "VIEW_EXTERNAL" : "http://buyers.test.onego.com/benefit/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr"
        }
    }
}

POST /benefits/{benefitId}/read

Marks benefit as read. Should be issued on benefit, whose details are displayed and which has Benefit.hasBeenRead set to false.

Request

Type Name Description Constraints
URI {benefitId} Unique benefit identifier. Required

Response

200 OK.

Example

curl -X POST \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/read

POST /benefits/{benefitId}/view

Marks benefit as viewed. Should be called every time benefit details are being viewed.

Request

Type Name Description Constraints
URI {benefitId} Unique benefit identifier. Required

Response

200 OK.

Example

curl -X POST \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/view

POST /benefits/{benefitId}/donate

Donates a benefit of type DONATION. Buyer must have enough funds to be able to donate. Prices of benefits (required funds) are provided in Benefit eligibility price field.

Request

Type Name Description Constraints
URI {benefitId} Unique benefit identifier. Required

Response

200 OK.

Example

curl -X POST \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/donate

POST /benefits/{benefitId}/share

Shares benefit by email on buyer's behalf.

Request

Type Name Description Constraints
URI {benefitId} Unique benefit identifier. Required
JSON email Email address to send benefit URL to. Required

Response

200 OK.

Example

curl -X POST \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data '{"email":"friend@gmail.com"}' \
    https://api.onego.com/services/v1/benefits/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr/share

/bims resource

/bims resource is used for getting info and managing Buyer Identification Means (BIM).

Endpoint URI Authentication
GET /bims https://api.onego.com/services/v1/bims Required
POST /bims/card https://api.onego.com/services/v1/bims/card Required
POST /bims/phone https://api.onego.com/services/v1/bims/phone Required
POST /bims/phone/verify https://api.onego.com/services/v1/bims/phone/verify Required
POST /bims/barcode https://api.onego.com/services/v1/bims/barcode Required
GET /bims/{number} https://api.onego.com/services/v1/bims/{number} Required
POST /bims/{number}/block https://api.onego.com/services/v1/bims/{number}/block Required
POST /bims/{number}/unblock https://api.onego.com/services/v1/bims/{number}/unblock Required
POST /bims/{number}/remove https://api.onego.com/services/v1/bims/{number}/remove Required
GET /pass/{merchantId} https://api.onego.com/services/v1/bims/pass/{merchantId} Required
POST /pass/{merchantId} https://api.onego.com/services/v1/bims/pass/{merchantId} Required

GET /bims

Returns a list of buyers BIMs.

Request

None.

Response

Field Description
bims A list of BIM items
Action Description
ADD_CARD POST /bims/card to add card to buyer profile. Action uri is present only when additional card BIMs can be added - max allowed limit not yet reached.
ADD_PHONE POST /bims/phone to add mobile phone to buyer profile. Action uri is present only when additional phone BIM can be added - max allowed limit not yet reached.
CREATE_BARCODE POST /bims/barcode to create new barcode to buyer profile. Action uri is present only when additional barcode BIM can be created - max allowed limit not yet reached.

Example

Request:

curl --get \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/bims

Response:

{
    "bims" : [ {
        "type" : "CARD",
        "number" : "9915691760793",
        "status" : "ACTIVE",
        "bimUri" : "/services/v1/bims/9915691760793"
       } , {
        "type" : "PHONE",
        "number" : "37060000000",
        "status" : "ACTIVE",
        "bimUri" : "/services/v1/bims/37060000000"
       } ],
    "actionUris" : {
        "ADD_CARD" : "/services/v1/bims/card",
        "ADD_PHONE": "/services/v1/bims/phone"
        "CREATE_BARCODE": "/services/v1/bims/barcode"
    }
}

POST /bims/card

Add new card for authenticated buyer.

Request

Field Description
cardNumber Card number. EAN13 (length 13, numbers)
scratchCode Card scratch code.

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Errors

HTTP Status Error code Explanation
400 "bim_addition_throttled" Entered invalid card number/scratch code too may times.
400 "bim_limit_reached" Max number of allowed cards reached.
400 "bim_already_exists" This card has already been added.
400 "bim_state_invalid" Provided card either not yet activated, belongs to different user, etc.

Example

curl -X POST  \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data '{"cardNumber" : "9915691760793", "scratchCode" : "123123"}' \
    https://api.onego.com/services/v1/bims/card

POST /bims/phone

Add new mobile phone number for authenticated buyer.

Request

Field Description
countryCode Two letter ISO country code.
phoneNumber Mobile phone number. Can be both in local and international format.

Response

Action Description
VERIFY_PHONE POST /bims/phone/verify verify added mobile phone number with received SMS code.

Errors

HTTP Status Error code Explanation
400 "bim_already_exists" This phone BIM has already been added.
400 "bim_state_invalid" Provided card has not yet been activated, belongs to a different user, etc.

Example

Request:

curl -X POST  \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data '{"countryCode" : "US", "phoneNumber" : "555-555-5555"}' \
    https://api.onego.com/services/v1/bims/phone

Response:

{
    "actionUris" : {
           "VERIFY_PHONE": "/services/v1/bims/phone/verify"
      }
}

POST /bims/phone/verify

Verifies phone number that authenticated buyer previously added. Verification code is received via sms.

Request

Field Description
countryCode Two letter ISO country code.
phoneNumber Mobile phone number. Can be both in local and international format.
verificationCode Mobile phone verification code received via SMS.

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Errors

HTTP Status Error code Explanation
400 "bim_addition_throttled" Entered invalid phone number/scratch code too may times.
400 "bim_limit_reached" Max number of allowed phone bims reached.
400 "bim_already_exists" This phone bim already added.
400 "bim_state_invalid" Provided card either not yet activated, belongs to different user, etc.

Example

curl -X POST  \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data '{"countryCode" : "US", "phoneNumber" : \
          "555-555-5555", "verificationCode" : "00000"}' \
    https://api.onego.com/services/v1/bims/phone/verify

POST /bims/barcode

Create new barcode BIM for authenticated buyer.

Only one barcode BIM may be active at a time. Old barcode bim must be removed before attempting to create new one.

Request

None.

Response

Field Description
number Newly created barcode BIM number.

Errors

HTTP Status Error code Explanation
400 "bim_already_exists" Barcode BIM already exists.

Example

Request:

curl -X POST  \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/bims/barcode

Response:

{
    "number": "9916123456789"
}

GET /bims/{number}

Get BIM by its number for an authenticated buyer.

Request

Type Name Description Constraints
URI {number} Unique BIM identifier (phone/card/barcode number or email address). Required

Response

A single BIM item. (EMAIL type BIMs do not have actionUris).

Example

Request:

curl --get \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/bims/9915691760793

Response:

{
    "bim" : {
        "type" : "CARD",
        "number" : "9915691760793",
        "status" : "ACTIVE",
        "bimUri" : "/services/v1/bims/9915691760793"
    },
    "actionUris" : {
        "BLOCK" : "/services/v1/bims/9915691760793/block",
        "REMOVE" : "/services/v1/bims/9915691760793/remove"
    }
}

POST /bims/{number}/block

Block BIM by number with status change reason for authenticated buyer. Email and barcode BIMs cannot be blocked.

Request

Type Name Description Constraints
URI {number} Unique BIM identifier (phone or card number). Required
JSON BIM status change request. - Required

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Errors

HTTP Status Error code Explanation
400 "bim_state_invalid" Tried to block already blocked BIM.

Example

Request:

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data '{"reason" : "LOST"}' \
    https://api.onego.com/services/v1/bims/9915691760793/block

POST /bims/{number}/unblock

Unblock a BIM by its number with status change reason for authenticated buyer. Email BIMs cannot be unblocked.

Request

Type Name Description Constraints
URI {number} Unique BIM identifier (phone or card number). Required

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Errors

HTTP Status Error code Explanation
400 "bim_state_invalid" Tried to unblock active BIM.

Example

Request:

curl -X POST \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/bims/9915691760793/unblock/

POST /bims/{number}/remove

Remove BIM by number with status change reason for authenticated buyer. Email BIMs cannot be removed.

Request

Type Name Description Constraints
URI {number} Unique BIM identifier (phone or card number). Required
JSON BIM status change request - Required

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

Request:

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --data '{"reason" : "LOST"}' \
    https://api.onego.com/services/v1/bims/9915691760793/remove

GET /bims/pass/{merchantId}

Returns an Apple Passbook file.

Request

Type Name Description Constraints
Path param {merchantId} Unique merchant identifier. Required

Response

A Passbook file.

Example

Authenticated request:

curl --get \
--header "Accept: application/json, application/vnd.apple.pkpass" \
--header "Authorization: Bearer ACCESS_TOKEN" \
https://api.onego.com/services/v1/bims/pass/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

POST /bims/pass/{merchantId}

Sends a Passbook file to a specified email.

Request

Type Name Description Constraints
Path param {merchantId} Unique merchant identifier. Required
Data email Email address to send Passbook file to. Required

Response

200 OK on success, or HTTP error response with corresponding JSON.

Example

Authenticated request:

curl -XPOST \
--header "Accept: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--data '{"email":"email@example.com"}' \
https://api.onego.com/services/v1/bims/pass/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

/location resource

/location base resource is a placeholder for location related operations.

Endpoint URI Authentication
GET /location/cities https://api.onego.com/services/v1/location/cities Required
GET /location/supported_countries https://api.onego.com/services/v1/location/supported_countries Not required
GET /location/supported_states https://api.onego.com/services/v1/location/supported_states Not required
GET /location/phone_codes https://api.onego.com/services/v1/location/phone_codes Not required

GET /location/cities

Fetch cities by provided country/state. Search is performed only if at least 3 symbols are provided via 'query' parameter.

Note: countries that support city search can be fetched via GET /location/supported_countries resource. Countries that need state to be provided can be fetched via GET /location/supported_states endpoint.

Request

Type Name Description Constraints
Query query City title fragment from the start (case insensitive). For example to match 'New York City' you should provide 'new', 'New York'. Optional
Query country 'ISO 3166-1 alpha-2' country code. Required
Query state 'ISO_3166-2' subdivision/state codes. Mandatory for countries for which states matter. Non-existent state is not treated as error case, for example search query:new, country:US, state:XX will simply return empty result. Optional
Query limit How many results to fetch. Optional, defaults to 100 if not provided

Response

A list of City objects.

Example

Request:

curl --get \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    https://api.onego.com/services/v1/location/cities?query=Beth&country=US&state=DE

Example response:

{
    "cities" : [ {
        "name" : "Bethel",
        "county" : "Sussex"
      }, {
        "name" : "Bethany Beach",
        "county" : "Sussex"
    } ]
}

GET /location/supported_countries

Returns list of countries, that support city search. This resource is not intended for online access, but instead for exporting list of supported countries for inclusion with application being shipped. Produces both json and xml formats.

Request

None.

Response

A list of Country objects.

Example

Request for JSON:

curl --get \
    --header "Accept: application/json" \
    https://api.onego.com/services/v1/location/supported_countries

Response:

{
    "countries" : [ {
        "name" : "Canada",
        "code" : "CA"
      }, {
        "name" : "United States of America",
        "code" : "US"
      } ]
}

GET /location/supported_states

Returns list of countries with states, that support city search. This resource is not intended for online access, but instead for exporting list of supported states for inclusion with application being shipped. Produces both JSON and XML formats.

Request

None.

Response

A list of Country with states objects.

Example

Request for JSON:

curl --get \
    --header "Accept: application/json" \
    https://api.onego.com/services/v1/location/supported_states

Response:

{
    "countries" : [ {
        "code" : "US",
        "name" : "United States of America",
        "states" : [ {
            "name" : "Ohio",
            "code" : "OH"
          }, {
            "name" : "Nevada",
            "code" : "NV"
          }, {
            ...
          }, {
            "name" : "Massachusetts",
            "code" : "MA"
          }, {
            "name" : "Texas",
            "code" : "TX"
          } ]
      } ]
  }

GET /location/phone_codes

Returns a list of phone codes with countries. This resource is not intended for online access, but instead for exporting list of country phone codes for inclusion with application being shipped. Produces both JSON and XML formats.

Request

None.

Response

A list of PhoneCode objects.

Example

Request for JSON:

curl --get \
    --header "Accept: application/json" \
    https://api.onego.com/services/v1/location/phone_codes

Response:

{
    "phoneCodes" : [ {
        "code" : "+1"
        "country" : "United States of America",
        "countryCode" : "US"
      }, {
        "code" : "+1",
        "country" : "Canada",
        "countryCode" : "CA"
      } ]
}

/statement resource

/statement resource is used to get information about buyer transactions.

Endpoint URI Authentication
GET /statement/{merchantId} https://api.onego.com/services/v1/statement/{merchantId}?starting={starting}&ending={ending} Required

GET /statement/{merchantId}?starting={starting}&ending={ending}

Returns a list of buyer transactions at given merchant.

Request

Type Name Description Constraints
Path param {merchantId} Unique merchant identifier. Required
Query param {starting} Starting date for the items list. Must be ISO 8601 date format if provided. Optional
Query param {ending} Ending date for the items list. Must be ISO 8601 date format if provided. Optional

Response

A list of Transaction items.

Example

Authenticated request:

curl --get \
--header "Accept: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
https://api.onego.com/services/v1/statement/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

Response:

[
    {
        "time" : "2012-07-04T12:08:56+0200",
        "payable" : "12.50",
        "spent" : "10.00",
        "received" : "0.10",
        "status": "DELAYED"
    }, {
        "time" : "2012-07-05T12:08:18+0200",
        "payable" : "1.50",
        "spent" : "0.40",
        "received" : "0.00",
        "status": "CONFIRMED"
    },{
        "time" : "2012-07-06T10:08:56+0200",
        "payable" : "11.70",
        "spent" : "0.00",
        "received" : "0.12",
        "status": "PENDING",
        "validFrom": "2012-07-08T10:08:56+0200"
    }
]

Authenticated request:

curl --get \
--header "Accept: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
https://api.onego.com/services/v1/statement/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr?starting=2012-05-12&ending=2012-07-05

Response:

[
    {
        "time" : "2012-07-04T12:08:56+0200",
        "payable" : "12.50",
        "spent" : "10.00",
        "received" : "0.10",
        "status": "DELAYED"
    }, {
        "time" : "2012-07-05T12:08:18+0200",
        "payable" : "1.50",
        "spent" : "0.40",
        "received" : "0.00",
        "status": "CONFIRMED"
    }
]

/redeem resource

/redeem resource is used for code redeeming.

Endpoint URI Authentication
POST /redeem/{code} <https://api.onego.com/services/v1/redeem/{code} Required

POST /redeem/{code}

Transfers redemption code funds balance to buyer prepaid account.

Request

Type Name Description Constraints
Path param {code} Unique redemption code. Required

Response

Field Description
merchantId Id of a merchant which spread redemption code.
merchantBrandName Merchant brand name which spread redemption code.
redeemedAmount Funds amount that was transferred to buyer prepaid account at the identified merchant.

Example

Authenticated request:

curl --get \
--header "Accept: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
https://api.onego.com/services/v1/redeem/ABC123

Response:

{
    "merchantId" : "qfwh2gkh3155gnzxd4sfbwtouoaoyi2vgzlv",
    "merchantBrandName" : "Tom's Cookies'n'Pies",
    "redeemedAmount" : "10.00"
}

/eula resource

/eula resource is used for buyer EULAs management.

Endpoint URI Authentication
GET /eula https://api.onego.com/services/v1/eula Required
GET /eula/{merchantId} https://api.onego.com/services/v1/eula/{merhantId} Required
POST /eula https://api.onego.com/services/v1/eula Required
POST /eula/{merchantId} https://api.onego.com/services/v1/eula/{merchantId} Required

GET /eula

Returns if buyer needs to accept newer OneGo EULA.

Request

None.

Response

EULA status.

Example

Authenticated request:

curl --get \
--header "Accept: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
https://api.onego.com/services/v1/eula

Response:

{
  "onegoAccepted" : true
}

GET /eula/{merchantId}

Returns if buyer needs to accept newer OneGo or merchant EULA.

Request

None.

Response

EULA status.

Example

Authenticated request:

curl --get \
--header "Accept: application/json" \
--header "Authorization: Bearer ACCESS_TOKEN" \
https://api.onego.com/services/v1/eula/qfwh2gkh3155gnzxd4sfbwtouoaoyi2vgzlv

Response:

{
  "onegoAccepted" : true,
  "merchantAccepted" : false
}

POST /eula

Indicates that buyer accepted latest OneGo EULA.

Request

None.

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

Authenticated request:

curl -X POST  \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  https://api.onego.com/services/v1/eula

POST /eula/{merchantId}

Indicates that buyer accepted latest merchant EULA. Latest OneGo EULA can be marked accepted in the same call.

Request

Type Name Description Constraints
Data merchantAccepted Indicates that merchant EULA was accepted. Only allowed value can be boolean true Required
Data onegoAccepted OneGo EULA can be accepted in the same call. Only allowed value can be boolean true Optional

Response

200 OK on successful update, or HTTP error response with corresponding JSON.

Example

Authenticated request:

curl -X POST  \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"merchantAccepted": true, "onegoAccepted":true}' \
  https://api.onego.com/services/v1/eula/coq3eltd1nfwseu8brk0df2shqu6y53ig8spsr

JSON structures

Bim status change request

Fields

Field Description
reason Bim status change reason, one of: NONE, OTHER, LOST, SCAM. In case reason is set to OTHER, 'reasonText' must be provided.
reasonText Bim status change reason text for Reason.OTHER.

BIM item

Fields

Field Description
bimUri Relative URI to BIM endpoint.
number BIM number.
type One of CARD, PHONE, EMAIL, BARCODE.
status Any of ACTIVE, BLOCKED.

Actions

Field Description
BLOCK POST /bims/{number}/block to block buyer BIM if BIM is not blocked.
UNBLOCK POST /bims/{number}/unblock to block buyer BIM if BIM is blocked.
REMOVE POST /bims/{number}/remove to remove buyer BIM.

Merchant item

Fields

Field Description
title Merchant title.
imageUris URIs to resized merchant logo. In case merchant did not set any image, URIs of default static image will be returned. Resized image version will always be available, see Image URIs for more details.
activeBenefitCount Number of new deals/benefits in merchant inbox.
unreadBenefitCount Number of deals/benefits that buyer has not yet viewed.
prepaid Buyers fund balance of prepaid. Available only for authenticated request.
isFriend Is buyer connected to merchant. Available only for authenticated request.
currency Merchants currency code. Always present.
status One of ACTIVE, BLOCKED.
prepaidEnabled Tells whether this merchant has prepaid enabled.
barcodeType Barcode type (EAN13, QR, AZTEC, or PDF417) supported by the merchant. Available only when merchant supports barcodes to identify buyer.

Actions

Field Description
INBOX GET /merchants/{id}/inbox
CONNECT POST /merchants/{id}/connect to connect to the merchant. Available only for authenticated request.
DISCONNECT POST /merchants/{id}/disconnect to disconnect from the merchant. Available only for authenticated request.

Store item

Fields

Field Description
title Merchant Store title.
description Merchant Store description.
activeBenefitCount Number of new deals/benefits in merchant inbox. Available only for authenticated request.
features A list of Store features. Possible features: WIFI - free WiFi network, PARKING - free parking.
phone Store phone number in local format.
address Store address structure.
workingTime Map of store working time for each weekday. In case store is closed during one of the weekday this day is not included in the map. Possible weekdays: MON, TUE, WED, THU, FRI, SAT, SUN.
coordinates Store coordinates in WGS 84 system.

address

Field Description
address Free-form address line.
cityName City name.
stateName State name.

workingTime Map representing working time for every working weekday. Possible weekdays: MON, TUE, WED, THU, FRI, SAT, SUN. Each working day is representing using structure:

Field Description
starting Store opening time .
ending Store closing time.

coordinates

Field Description
latitude Store geographic coordinate latitude in WGS 84.
longitude Store geographic coordinate longitude in WGS 84.

Benefit item

Fields

Field Description
benefitUri URL to GET /benefits/{benefitId}.
imageUris URIs to resized benefit images. In case image was not set, URIs of default static image will be returned. Static image varies by Benefit type. Resized image version will always be available, see Image URIs for more details.
title Benefit title.
description Benefit description.
contract Additional benefit details.
validUntil Date when benefit expires - not mandatory.
type PREPAID - prepaid reward, OFFER - offer/benefit, DONATION - donation type offer.
status ACTIVE - currently active benefit, ELIGIBLE - buyer has yet to fulfill specific benefit rules to obtain this benefit.
eligibility Rules for obtaining this offer, applicable only for OFFER or DONATION type benefit.
count Indicates number of instances for the same offer.
awardedCount Indicates how many times buyer has already satisfied conditions of given benefit and got the award. If not present, means that awardCount is not applicable for this type of benefit.
flags A list of benefits flags, that indicate one or other property on benefit. Possible choices: SHAREABLE - benefit can be viewed by anyone, NOT_READ - benefit has not been marked as read (authenticated user did not view it's details on any onego application).
limited This property is set only when offer has global usage count limit. Returns Progress DTO.

Actions

Field Description
MARK_VIEWED POST /benefits/{benefitId}/view to mark benefit as viewed.
MARK_READ POST /benefits/{benefitId}/read to mark benefit as read.
VIEW_EXTERNAL External link to benefit page inOneGo buyer portal.
DONATE POST /benefits/{benefitId}/donate donate benefit, only applicable for DONATION type benefit.

Fund Balance item

Fields

Field Description
currentBalance Current balance of provided fund type in buyers account.
futureBalance Balance of provided type funds, that are available, but not yet redeemable. Ex. buyer received monetary points, but due to globally set redeem delay buyer cannot yet spend these funds and they will become active after certain period.

Actions

None.

Benefit eligibility rules

Field Description
type One of TRANSACTION_SUM, TRANSACTION_COUNT, STEP_OFFER.
current Current progress.
threshhold How much of amount/items has to be collected to obtain the benefit.
steps Set only for type='STEP_OFFER'. List of available steps.
price Benefit price, only applicable for DONATION type benefit. Indicates how much in PREPAID funds buyer has to have to be able to donate given benefit.
unclaimedAwardCount Indicates how many unclaimed awards belong to buyer. Not present if zero.

Actions

None.

Progress

Fields

Field Description
current Current progress.
threshhold Initial limit.

Actions

None.

Image URIs

Map representing available image URIs with available sizes.

Available sizes

Size Formats to expect Description
original unpredictable URI to the original image, size and edge proportion is unpredictable. Optional, however, if provided, other sizes will not be available.
45x45 png, jpeg URI to square 45x45px__ resized image.
110x110 png, jpeg URI to square 110x110px resized image.
200x200 png, jpeg URI to square 200x200px resized image.
300x300 png, jpeg URI to square 300x300px resized image.

Examples

When resized version is available:

{
    ...
    "imageUris" : {
        "45x45": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/small.jpeg?v=7",
        "110x110": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/large.jpeg?v=7",
        "200x200": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/larger.jpeg?v=7",
        "300x300": "https://onego-img.s3.amazonaws.com/user/rb4783imhf4pgn2/huge.jpeg?v=7"
    }
    ...
}

When only original version is available:

{
    ...
    "pictureUris" : {
        "original": "http://example.com/external/resource/image.jpg"
    }
    ...
}

Country

Fields

Field Description
alpha2Code ISO 3166-1 alpha-2 country code.
name Country name.
states An optional list of states.

State

Fields

Field Description
code Local state code.
name State name.

City

Fields

Field Description
name Name of city.
county County to which city belongs.

PhoneCode

Fields

Field Description
code Country phone code.
country Country name.
countryCode ISO 3166-1 alpha-2 country code.

Transaction item

Fields

Field Description
time Transaction date time in ISO 8601 format. In most of a cases timezone will be same for all transactions, however it might be different for merchant operating in country with several timezones (i.e USA).
payable Amount which buyer had to pay.
spent Amount spent using buyer prepaid account.
received Amount received to buyer prepaid account.
status Transaction status. Might be one of ["PENDING", "DELAYED", "CONFIRMED"].
validFrom If transaction status is "PENDING", this field indicates when received amount becomes available. Same assumptions regarding time zone apply as for time field.
validTo Date when amount received expires. Not included if received amount don't have expiration set. Same assumptions regarding time zone apply as for time field.

Periodicity

Fields

Field Description
IMMEDIATELY Notifications will be sent immediately.
DAILY Notifications will be sent once a day.
WEEKLY Notifications will be sent once a week.
NEVER Notifications will not be sent.

EULA status

Fields

Field Description
onegoAccepted Boolean flag indicating if OneGo EULA must be accepted.
merchantAccepted Boolean flag indicating if merchant EULA must be accepted. Not available in GET /eula.