Solicitation API

Introduction

The process flow is as follows:

1. Transaction is registered on customer system.

2. Customer system triggers Rant & Rave service via HTTPS.

3. Solicitation API service validates and processes the request based on the criteria set.

4. Data is passed to the correct survey channel (depending on the chosen workflow) and metadata is stored in the Rant & Rave database.

5. Result of the survey is logged in the database for review on request.

Access

The API is made available at solicit.rantandrave.co.uk.

Authentication

To trigger, the customer must authenticate with the system, the username and password will be configured within the Rant & Rave platform as a normal user but with solicitation access rights.

Request Format

The request will be restricted in the following format:

POST https://solicit.rantandrave.co.uk/outbound/<project>/solicit/ username=<username>

password=<password> recipient=<recipient> workflow=<workflow_name> schedule=<schedule_date_time_iso_8601> window=<sociable_hours_window> grace=<grace_period_seconds> priority=<priority> reference=<reference_text> meta={"<column1>": "<value1>", ... }

The post format (Content-Type) should be aplication/x-www-form-urlencoded (standard HTML form encoding). The same is available using the GET verb for legacy systems at /outbound/<project>/solicit/post/.

On success, this returns status 200 with JSON:

{"UUID":"<uuid_for_item>"}

On failure, it will return a non-200 status code, with a human-friendly description in the content to help debugging. The status may be:

• Recipient: The target for the survey request. This is a mandatory column.

• Workflow: It enables for multiple workflows to be defined. This is a non-mandatory column and it will use the project default, if missing.

• Meta: The JSON structure fr the metadata to be appended to feedback request. This is a mandatory column unless no metadata is required.

There are also several optional control fields which can be used:

• Grace: For each recipient it is possible to define the minimum time (in seconds) between re-surveying a single customer. this value allows for the default periods to be overridden. this is a non-mandatory column and it will use the workflow or project default, if missing.

• Schedule: It defines the time (in ISO8601 format) that the record should be sent. This is a non-mandatory column and it will be immediate, if missing.

• Window: It defines the sociable contact time window whena record is permitted to be sent. This is a non-mandatory column and it will use the workflow or project default, if missing.

• Priority: It defines that relative priority for a message compared with other items in the batch and other batches for the same project (lower numbers are handled before higher numbers). This is a non-mandatory column and it will be "2", if missing.

• Reference: Any reference text which will be provided back in any log requests for this item. This is a non-mandatory column and it will be blank, if missing.

Scheduling, Sociable Hour Windows and Grace Periods

The schedule determines (on a per-message basis) the earliest time at which an item can be processed. The message may be sent later than this if the service is busy. For example, scheduling a large batch to be sent at the same time will queue the messages.

Once the scheduled time is reached. the sociable hours are checked to ensure that the message should be sent. If it is not within the given sociable hours (either because the scheduled time was outside the hours or the size of the queue has pushed the dispatch beyond the sociable hours). the message will be rescheduled for the next available sociable time (the reported scheduled time will still show the original schedule).

Once a message can be sent within sociable hours, the grace period is checked as well as whether the user has opted out. If the user was contacted within the grace period or if the user is currently opted out, the message is abandoned. Otherwise, the message will be sent.

If you send multiple solicitations in the same second, it can prevent the grace period from being processed. This can result in multiple solicitations being sent to the same recipient within the grace period. To prevent this, either avoid sending multiple solicitations in quick succession or throttle your solicitation requests when you send several at the same time.

Solicitations will not be sent outside fo the specified sociable hours window though they may be received outside the times. For example, if a mobile phone is turned off or has no signal when the message is sent or due to network delays.

The format for the schedule is ISO 8601 (YYYY-MM-DDThh:mm:ssZ). Fractional seconds are permitted. The format for the sociable hours range is hh:mm:ss/hh:mm:ssZ (e.g., 09:00:00/21:00:00Z to limit the hours to between 9am to 9pm). Hours are between 0 and 23 (inclusive), minutes are between 0 and 59 (inclusive), seconds are between 0 and 59 (inclusive). Seconds can be omitted.

Ranges can also be combined with commas and optional spaces (e.g., 09:00:00/12:00:00,16:00:00/21:00:00Z to limit the hours to between 9am and midday, or 4pm and 9pm). Time ranges can overlap. The time ranges are always taken in forward direction (e.g., 21:00:00/03:00:00Z will create a range from 9pm through midnight to 3am).

The time zone specifier (z for UTC/GMT) should only be given on the last time in the list and may be preceded by an @ symbol. A geographic time zone can also be specified which will allow for daylight savings time, if applicable. For example, 09:00/21:00@Europe/London.

The geographical time zones accepted can be found in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones (case sensitive).

It is possible to specify days of the week as Mon/Fri 09:00:00/21:00:00, Sat 11:00:00/21:00:00@Z. It will use 9am-9pm Monday to friday, 11am to 9pm on Saturday, and never send on a Sunday. If the time range crossed midnight, it is the start of the time range which is matched to the given day of the week. Any time range which does not include a day of the week is assumed to be everyday.

Specific dates can also be given special rules. For example, to prevent sending messages on the 1st of January, you can use Mon/Fri 09:00/21:00, 1-Jan -@Z. Similarly, to prevent sending on May Day (the first Monday of May) you can use Mon/Fri 09:00/21:00, Mon1-May -@Z.

Note: The "-" is a special time range meaning no times are valid on the matching day. This is only available when specifying times for specific days.

Summary

It is recommended to make each time range at least several hours to ensure messages will not build up due to lack of processing time.

The status of each record will be one of the following:

If the status has failed, the human readable failure reasons will be one of the following:

Again, this file is also available as <uuid>-log.csv, though this file only included the records and does not include the header information.

To reduce the duplication of data, the metadata is not included in these log files. the original files are also available at /<project_dir>/outbound/solicitation/logs/batches/<yyyy>/<mm>/<dd>/<uuid>.csv, where .csv is whatever format was originally uploaded. These files will be available for at least 1 month after being uploaded, then may be archived or deleted, manually or automatically.