REST API

Basic concepts

This section explains required basic concepts when working with the dialogportal™ REST API. It documents the location of the API, how to use and work with keys and contracts

Authenticating requests

For an application to be allowed to make calls to the API, it must send a signature with every request. The signature is a JSON string passed in the HTTP Header

• Authenticating from JavaScript — Authenticating from JavaScript is different to standard API authentication, since the standard authentication mechanism would expose the AppSecret in a purely client-based application, which would be a serious security breach. This article provides technical details of the JavaScript authentication process. For general use, see JavaScript SDK.
• Public authentication

Standard status codes

The complete list of HTTP status codes returned by the API.

• Non-standard reporting of status — In some cases a client application may be unable to handle reporting of status using HTTP status codes. In this case, dialogportal™ is able to handle reporting of status to that specific application using JSON data in the response body. This article explains non-standard reporting of status

Endpoints

• Account management
  • 1001: Create account — Creates a new entity/user account in the Rubiq database with fields specified in a contract between the calling application and the Rubiq platform. A unique Rubiq entity ID is automatically assigned to the new entity, and optionally a key with an external type.
  • 1002: Get account data — Retrieves data for an entity/account. The returned data will always contain the Rubiq entity ID and optionally a key with an external type. In addition, the payload contains the data specified in the contract between the calling application and the Rubiq API.
  • 1003: Update account data — Validates that the data complies with possible rules and performs the update if it does. Only the data provided in the payload is updated. The calling application must have permission to update accounts.
  • 1004: Remove account — Deletes an entity/account. The calling application must have permission to delete accounts.
  • 1005: Create child — Creates a new entity/account as a child of another entity in the Rubiq database, with fields specified in a contract between the calling application and the Rubiq API. The parent-child relationship between the entities must be previously established in Rubiq Cloud.
  • 1006: Enumerate children — Retrieves all the children for an entity/account. The returned data will always contain the Rubiq entity ID and optionally a key with an external type for each of the children. In addition, the payload may optionally contain the data for each child as specified in the contract between the calling application and the Rubiq API.
  • 1007: Connect to track — Connects an entity/account to a track
  • 1008: Disconnect from track — Disconnects an entity/account from a track. The connection between the entity and the track is not removed, but the state is changed to "disconnected".
  • 1009: Enumerate tracks — Retrieves an enumeration of all the tracks an account is connected to.
  • 1010: Determine track connection — Determines if an account is connected to a track 
  • 1011: Search — Searches the entire Rubiq database for accounts which match a given search string.
  • 1012: Create changed since session — Begin a search session to find all Rubiq entities that have been modified since a given date, and return the session token identifier.
  • 1013: Get changed since — Return entities for a search session specified by a token identifier.
  • 1020: Create account with children — Creates a new user entity and child entities in a single request. This endpoint is a combination of endpoints 1001: Create account and 1005: Create child.
  • 1050: Evaluate loyalty scheme — Evaluates a loyalty scheme for an entity
• Lead management
  • 1100: Create lead — Creates a new Lead entity. The leadSourceID and all fields are configured within the Rubiq Lead Management app.
  • 1101: Get lead source fields — Returns the required and optional fields used in Lead creation.
• Account authentication
  • 2001: Authenticate — Authenticates an entity by checking whether, for example, the submitted username and password matches the data in the database, or a specific account on a social media is registered in the database.
  • 2002: Change password — Updates password of an entity after first having verified that the old password is correct and matches entity
  • 2003: Trigger “Forgotten password” service — Initiates communication flow when a user has forgotten their password. What specifically happens must first be configured in Rubiq Cloud.
  • 2004: Verify account — Activates an entity/account, when the contract specifies that all new entities must be verified before they can be used.
  • 2005: Request onetime-password — Requests that the API generate a onetime-password to be emailed to an entity email address. The password can then be used to authenticate using authType: onetime, with endpoint 2001: Authenticate.
• Loyalty
  • 2200 Register participant — Register a participant in instant win
• Entity Preferences
  • 2316: Opt-out of preference — Update entity preference subscription status: Opt-out
  • 2305: Get preference groups — Fetch preference group details
  • 2310: Get preference opt-in status — Fetch entity preference subscription details for all preferences
  • 2317: Update entity preferences for group — Update entity preference subscription status for all preferences in a group
  • 2315: Opt-in to preference — Update entity preference subscription status: Opt-in
  • 2300: Get preferences — Fetch preference details
  • 2311: Get individual preference opt-in status — Fetch entity preference subscription details for a single preference
  • 2318: Update specific entity preferences — Update entity preference subscription status for given preferences
  • 2312: Get preference group opt-in status — Fetch entity preference subscription details for all preferences in a group
• Social connections
  • 3001: Get social connections — Returns information about all the social media that a given entity is connected to.
  • 3003: Add social connection — Connects an account with a specific social media.
  • 3002: Get social connection — Returns information about a specific connection between a given account and a social media.
  • 3004: Remove social connection — Removes the connection between an account and a social media.
• Mobile devices
  • 4001: Register mobile device — Registers a mobile device to an entity. Registration may optionally contain information about the device token for dispatch of push messages. This end point should be called once every time the mobile app is started. 
  • 4002: Sign out mobile device — Turn off push messaging for a device until it is registered again
  • 4003: Get device — Fetches the mobile device details.  For iOS, this will only ever be the device id. For other device types (Android, WindowsPhone, Windows8 and BlackBerry), the current "push" status is also included, indicating whether push communications may be sent to this device.
• Transactions
  • 5002: Has transaction — Returns a boolean value indicating whether a transaction has been logged for the user with a specific group and type - optionally filtered by time period.
  • 5004: Enumerate transactions — Retrieves transactions that have been logged for the user with a specific group - optionally filtered by type and time period, with "paging" options (limit and offset)
  • 5001: Register a transaction — Stores information about a transaction made by a person. A transaction may for instance be some kind of action, a purchase, redemption of a coupon or a transaction on a points account or cash account
  • 5003: Sum transactions — Returns a sum total of the transactions for a user in a specific transaction group, optionally filtered by transaction type and time period.
• Miscellaneous services
  • 6001: Lookup city from zip code — Returns the correct city name based on country code and zip code
  • 6010: Parse phone number — Validate phone number and return valid phone number country code, country dial code and number type
  • 6011: Format phone number — Validate phone number and return the correctly formatted valid number in the requested format
  • 6012: Format phone number for out of country calling — Validate phone number and return the correctly formatted valid number ready to be called from a given country.
  • 6013: Get phone number description — Validate phone number and return the localized country name that the number is from
  • 6100: Generate access token — Generates a unique new token string, which may subsequently be used as a generic access token for a limit time.
• Communication
  • 7001: Get messages — Retrieves all available push communication messages for an account.
  • 7002: Get message — Retrieves a specific push communication message for an account.
  • 7003: Set message status — Marks the read status for a specific message.
  • 7004: Delete message — Removes a specific message from the list of displayed messages.
• Forms
  • 8006: Enumerate fields — Retrieve a list of fields for a form
  • 8005: Enumerate forms — Retrieve a list of all currently active forms available to an account
  • 8001: Submit form data — Submit form data for a user
  • 8002: Get form data — Retrieves the previously submitted form data
• Content
  • 9004: Private content search — Search for content available to a specific entity. The result may also include public content.
  • 9008: Reconnect entities — Replace the currently connected entities with a new array of entities. All previous connections will be removed for the content and the new array of entities connected instead.
  • 9002: Connect multiple entities — Connect an array of entities to content.
  • 9006: Enumerate tags — Fetch a list of all tags
  • 9001: Create content — Add tagged content to the system. The content must be published using endpoint 9003: Publish content before it can be accessed.
  • 9005: Public content search — Search for publicly available content
  • 9007: Remove content — Remove a tagged content item. Individual content items may be removed from the system, when they can be uniquely matched on tags and data.
  • 9002: Connect entity — Connect an entity to content. Once content has been connected to at least one entity, it is considered "private", and can only be accessed by entities that have been connected to it.
  • 9003: Publish content — Publish content, making it available to be used in search results.
• Media
  • 9100: Create media — Add a media file to the dialogportal™ Media Archive.
  • 9101: Update media — Update a media file in the dialogportal™ Media Archive.
• Documents
  • 9200: Get document — Retrieves document for an account.
  • 9205: Update document — Update a document for an account. This endpoint may also be used to move a document to another entity, by setting the moveToEntityID property.
  • 9203: Remove document — Removes a document for an account.
  • 9201: Get documents — Retrieves documents for an account.
  • 9202: Add document — Created a new document for an account.
  • 9204: Move documents — Move documents for an account to another account.
• Lotteries
  • 9400: Get active lottery — Returns the currently active lottery. If no lottery is currently active, a 404 response is returned.
  • 9401: Get upcoming lottery — Returns the next lottery which will become active in the future. If no upcoming lottery exists, a 404 response is returned.
  • 9402: Create reservation — Reserve a package of lottery numbers for a limited time.
  • 9403: Cancel reservation — Cancel a reservation of lottery numbers, making them available to others to purchase.
  • 9404: Pre-approve reservation — Pre-approve a reservation of lottery numbers, extending the reservation expiry time and preparing the reserved numbers for purchase. 
  • 9405: Approve reservation — Approve a reservation of lottery numbers. The reservation is marked as approved and a purchase is initiated with a 3rd-party payment provider.
  • 9406: Approve payment — Register the completed payment and complete the purchase.
  • 9407: Discard payment — Register a cancelled or discarded purchase of a lottery number reservation.
• Housekeeping
  • 1200: Trigger scheduled policy — Initializes a Housekeeping policy
  • 1201: Trigger policy for selection — Initializes a Housekeeping policy for an entity selection
  • 1203: Fetch execution status — Fetch the details of a Housekeeping execution
• Insights
  • 1300: Fetch consent stream data — Fetches a selection of consent data as a stream of actions
• Terms and Permissions
  • 2100: Get terms — Fetch terms
  • 2101: Get terms version — Fetch details for a specific terms version
  • 2102: Accept terms — Accept a set of terms for an entity
  • 2103: Get entity terms acceptance status — Fetch all sets of terms which the entity has accepted
  • 2104: Withdraw terms acceptance — Withdraw an entities acceptance of a set of terms
  • 2105: Accept permission — Accept a permission for an entity
  • 2106: Get entity permission acceptance status — Fetch all permissions the entity has given
  • 2107: Withdraw permission — Withdraw a permission for an entity
  • 2108: Get changes — Get a list of entities whose permissions have changed.
  • 2109: Update change cursor — Update the position of a change cursor
  • 2110: Update terms acceptance — Update the permissions/consents for a terms acceptance
  • 2111: Get terms version text for entity — Fetch a specific terms version text for an entity. 
  • 2112: Get terms version text — Fetch one or more terms version texts.
  • 2113: Get terms version file — Fetch a specific terms version file as a JSON string, containing the base64-encoded file.
  • 2114: Download terms version file — Fetch a specific terms version file as an HTTP download.
  • 2120: Get data requests — Fetch all data requests for an entity
  • 2121: Submit data request — Submit a new data request for an entity
  • 2122: Close data request — Close a data request for an entity, completing all incomplete actions
  • 2123: Complete data request action — Complete a data request action for an entity request

Security

• App Secret expiry — Gracefully expire an App Secret in order to migrate to a new one
• Password policy — Description of the various dialogportal™ REST API password restrictions and security settings
• Data Isolation — Use unique, user-specific ApiSessionKeys to limit API data access
• Illegal Access Prevention (IAP) — Block and report on undesirable API access attempts

Usage and Best Practices

Putting it all together: this section describes how to use the API to perform sign-up and login functionality etc.

• SMS Verification — Sign-up, authentication, verification, and changing a verified mobile number
• Basic Sign-up and API Interaction — Create and authenticate an entity, receive and use the dpKey
• UrbanAirship - Push notifications

JavaScript SDK

Web Components