Skip to main content

Appendices

Charles Jorgensen
Updated

Appendices

Appendix A - Sample Log files

General

  • The new file format is always UTF8.

  • Newlines are denoted by \r\n. Whitespace will not be added around commas or lines.

  • Typically, only fields containing commas will be quoted. Within the quotes, quote characters may be escaped with backslashes; my"file.txt" (similarly literal backslashes will be escaped; "my\\value"). Fields may be quoted even if they do not contain commas or quotes.

  • UUIDs will not be longer than 38 characters and may contain A-Z, a-z, 0-9, dash, and underscore characters. Beyond this, no character is guaranteed.

  • Times will always be in ISO8601 combined date and time format with a time zone (e.g., 2015-01- 30T15:20:44Z). Fractional seconds will not be included.

  • Column order is not guaranteed. More columns may be added in the future updates.

  • In the samples below, quoted values are representative (to indicate that any field may be quoted). They should not be taken to mean that specific fields will be quoted.

log.csv

Uploaded,Filename,"Status",UUID

2015-02-01T11:29:57Z,myFile1.xls,Pending,52BYb2fyWbu225 2015-02-01T12:30:13Z,myFile2.csv,Parsing,"39f8F7GH2gd32n" 2015-02-01T15:11:09+01:00,"oops.xlsx",Aborted,

<file>-log.csv

UUID,Recipient,Workflow,Schedule,Window,Grace,Processed,Status

hno87qdT337rHJ,+447000 000000,test1,2015-02-30T11:40:00Z,09:00:00/21:00:00Z,60,,Pending

HU387nOWnn8388,+447000000001,test2,,,,,"Failed (Invalid recipient)" i6IBY37nWgwfwk,+44 7000 000002,test1,"","","86400",2015-02-30T11:30:05Z,Successful

Appendix B

This API can also be used to solicit requests through a restful web request. The instructions below describe the methods to do this, and how to capture logs through the same service.

Note: Currently, the API is rooted at /outbound/<project>/solicit/. This does not match the /<project>/outbound/solicit/ structure of the FTP folders. A later release will correct this, but the current /outbound/<project>/solicit/ will continue to be supported.

The >project> identifier is a unique name for the project and is configured by Rant & Rave.

Making a Request

Single

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 application/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:

    Status Meaning
    400 Bad Request

    An invalid parameter was provided.

    Example: Window or JSON metadata.
    403 Forbidden

    The username/password provided was incorrect, or the user does not have permission to use the API.
    500 Internal Server Error

    The request may have been correct, but an internal error prevented it from being processed.

Batch via JASON

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

{

"username": "<username>",

"password": "<password>",

"batch": [

{

"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 application/json. All options except recipient (i.e., workflow, schedule, window, grace, meta) can also be specified at the root level. These will be used as defaults if not given for a batch item.

On success, this returns status as 200 with JSON:

{

"UUID": "<uuid_for_batch>",

"Batch": [

{

"UUID": "<uuid_for_batch_item_1>",

"Recipient":"<requested_recipient_1>",

"Reference":"<reference_1>"

},

{

"UUID": "<uuid_for_batch_item_2>",

"Recipient":"<requested_recipient_2>",

"Reference":"<reference_2>"

},

{

"Recipient":"<requested_recipient_3>",

"Error": "<reason_why_this_item_failed>"

}, {

},

...

]

}

"UUID": "<uuid_for_batch_item_4>", "Recipient":"<requested_recipient_4>".

Failed records will include n error reason but may not include a UUID. Failure reasons can include (for example) missing recipient values and invalid JSON structure. If the JSON structure is bad, the recipient may also be omitted (i.e., if it cannot be read from the input). Reference will be provided for any records which had a reference assigned (this can be a more reliable way to distinguish records when sending multiple messages to the same recipient).

The error messages returned at this point are purely structural/syntactial (i.e., there will not be errors due to using an unknown workflow name or attempting to send SMS messages to an email address, etc.). Typically, these errors should only be seen during development. The possible errors are:

Error Meaning
Invalid JSON structure

The structure of the JSON provided does not match the expected format.

Example: An array was found where a map was expected.
Invalid schedule

The schedule given could not be parsed.
Invalid window

The window given could not be parsed. This error will include a further explanation of why the window parsing failed.
Invalid recipient

If the requested recipient is missing.

Note: Except for this check, the recipient will not be checked for validity at this point.
Invalid workflow

If the requested workflow name is missing or too long.

Note: Except for this length check, the workflow name will not be checked for validity at this point.
Schedule is too far in the future

The requested scheduled time was more than a month into the future (checked at 32 days to allow some discrepancy), which is not supported.
Cannot schedule in the post

The requested scheduled time was in the past (some allowance is made for minor discrepancies, but if the scheduled time is more than 1 hour in the past, it will be rejected to avoid mistaken resubmissions).
Internal Error

There was an issue while handling the item. This message should never be seen.
Other

Other messages may be added in the future.

The batch UUID is only given if more than one item is requested. Otherwise, the request is handled as a standard (non-batch) request, and no batch UUID is generated:

{

// no uuid_for_batch here

"Batch": [

{

curl --data '{ "username": "<username>", "password": "<password>", "batch": [] }' -H "Content-Type: application/json"

"https://solicit.rantandrave.co.uk/outbound/<project>/solicit/"

{"Batch":[]}

curl --data '{ "username": "<username>", "password": "<password>", "batch": [ { "recipient": "me", "workflow": "stuff" }, { "recipient": "you", "workflow": "otherstuff" } ] }' -H "Content-Type: application/json"

"https://solicit.rantandrave.co.uk/outbound/<project>/solicit/"

{

"UUID": "aSVB6l-i2iLLdrJ-HJq6Yo1JLky7QZncnhNZ",

"Batch": [

{ "UUID": "a8ofo8TNTeIIIt4fCuxn1cXNUORgeZY_Hq-d", "Recipient": "me" },

{ "UUID": "aelyof_cIKkFERdpYOkrOlYWEdtzJMGBEB_f", "Recipient": "you" }

]

}

Batch via Spreadsheet

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

username=<username>

password=<password> batch=<csv or xlsx file>

The post format (Content-Type) should be multipart /form-data (standard HTML upload form). See SFTP part of API for details on spreadsheet format.

On success, this returns status 200 with JSON:

{

"UUID": "<uuid_for_batch>"

}

Note: You will not see UUIDs for each record when sending data this way. Your file will be queued internally for processing, so each record will not have a UUID immediately. This also means that you will not be alerted about invalid data or structure in the spreadsheet when using this method. The only way to check for these sorts of errors is to poll the lags explained below.

Canceling Requests

An additional feature available through the HTTP API which is not available through FTP is canceling solicitations. This can be achieved through either:

DELETE https://solicit.rantandrave.co.uk/outbound/<project>/solicit/solicitations/<uuid>/ username=<username>

password=<password>

or (for systems which cannot send alternative HTTP verbs):

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/solicitations/<uuid>/cancel/ username=<username>

password=<password>

Calling either of these endpoints will cause the item to be marked as canceled, returning HTTP 202 Accepted, or returning HTTP 410 Gone if the item has already been canceled. The response will not contain any body content.

Note: You will not receive any information about whether the item was successfully canceled (it may have already been processed).

If the item has already been sent, this will have no effect. If the item is still queued for sending (e.g., it is scheduled in the future or waiting for capacity), it will not be sent. You can whether an item was successfully cancel by checking its logs as described below.

Checking Status (logs)

These endpoints can be used to query the status of solicitations requested by any of the above methods. They can also be used to query the status of batches sent over SFTP. Similarly, you can use the SFTP system to query the status of batches sent via the REST API.

Note: The /logs/ component is for consistency with the SFTP folder structure, but in the spirit of RESTful endpoints you can omit this.

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/solicitations/<uuid>/ username=<username>

password=<password>

Returns JSON:

{

"UUID": "<uuid_for_item>", "Recipient": "<requested_recipient>", "Requested": "<date_of_request>",

"Schedule": "<requested_schedule_date>",

"Workflow": "<workflow_name>", May not be present "Grace": "<requested_grace_time_seconds>", May not be present "Priority": <requested_priority>,

"Reference": "<provided_reference_text>", "Meta": <requested_metadata>,

"Status": "<Pending|Cancelled|Successful|Failed>",

"Processed": "<date_of_processing>", Not present if Pending "Delivery": "<Unknown|Dispatched|Delivered|Received|Responded|Hard Bounce|Soft Bounce>",

"Error": "<error_description>", Present if Failed "Warnings": ["<warning_information>", ...] Present if Successful / Failed

}

Note: Delivery information is currently only available for email and voice solicitations. Also, the received and responded statuses are not yet available for email.

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/recipients/<recipient>/ username=<username>

password=<password>

Returns a list of all solicitations to the requested recipient. Note that the check is exact.

Example: If you send a message to 07000000000 and +447000000000, they will be considered different recipients. If there are no requests to show, the list will be empty.

The list is ordered by scheduled time (most recent first), and is currently limited to 50 entries, though this may change in future.

The JSON response is:

{

"Solicitations": [

{

<solicitation_as_described_above>,

...

}

]

}

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/batches/<uuid>/ username=<username>

password=<password>

Returns JSON:

{

"UUID": "<uuid_for_batch>", "Uploaded": "<date_of_request>",

"Filename": "<filename_when_uploaded>", "Status":

"<Aborted|Parsing|Pending|Progressing|Complete|Failed>", "Processed": "<date_of_processing>", Not present if Parsing or Aborted

"Records": <total_number_of_records_found>, Not present if Parsing or Aborted

"Successful": <records_successfully_sent>, Not present if Parsing or Aborted

"Pending": <records_waiting_to_be_sent>, Not present if Parsing or Aborted

"Failures": <records_which_failed_to_send>, Not present if Parsing or Aborted

"Cancelled": <records_cancelled>, Not present if Parsing or Aborted

"Error": "<error_description>" May not be present

}

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/batches/ username=<username>

password=<password>

Returns a list of years which have batch data, in JSON:

{

"Years": ["2014", "2015", ...]

}

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/batches/<year>/ username=<username>

password=<password>

Returns a list of month numbers which have batch data for the requested year in JSON:

{

"Months": ["01", "05", ...]

}

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/batches/<year>/<month>/ username=<username>

password=<password>

Returns a list of day numbers which have batch data for the requested year and month in JSON:

{

"Days": ["05", "30", ...]

}

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/batches/<year>/<month>/<day>/ username=<username>

password=<password>

Returns a list of batches submitted on the requested day.

The list is ordered by upload time (most recent first), and is currently limited to 1024 entries, though this may change in the future.

{

"Batches": [

{

<batch_as_described_above>,

...

}

]

}

GET https://solicit.rantandrave.co.uk/outbound/<project>/solicit/logs/batches/recent/ username=<username>

password=<password>

Returns a list of the most recent batches uploaded. This is ordered by upload time (most recent first) and is currently limited to 1024 entries or 1 hour (whichever is the more restrictive).

{

"Batches": [

{

<batch_as_described_above>,

...

}

]

}

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

Status Meaning
400 Bad Request

An invalid parameter was provided.

Example: An invalid year.
403 Forbidden

The username/password provided was incorrect, or the user does not have permission to use the API.
404 Not Found

A UUID you requested does not exist or is not linked to your account.
500 Internal Server Error

The request may have been correct, but an internal error prevented it from being processed.