Rest API

Authentication

All requests to this REST API must be authenticated with "Basic Authentication", using the users username and password. To avoid the users details being visible in the request to a third party, all requests to this API must be via HTTPS.

The authenticating user can be a User, Agent or Admin. The permissions of the user will determine what they can do.

To use Basic Authentication, the client adds the HTTP header "Authorization: Basic {credentials}" to the HTTPS requests where {credentials} is the base64-encoded string "your_username:your_password".

Most systems that programmatically access the web have options to add headers to requests, or can do the authentication for you. For example, he utility CURL has the -H option to add headers to the request, or you can add the parameter -u "login:password" and it will add the Authentication line for you.

If your username is "testuser" and your password is "testpassword" then you base64 encode the string "testuser:testpassword" getting "dGVzdHVzZXI6dGVzdHBhc3N3b3Jk"

So your HTTPS headers should include the line:

Authorization: Basic dGVzdHVzZXI6dGVzdHBhc3N3b3Jk

For example, using CURL, you could user either:

curl https://api.melcloud.welcorp.com/api/v1/jobs -H "Authorization: Basic bG9naW46cGFzc3dvcmQ"

or

curl https://api.melcloud.welcorp.com/api/v1/jobs -u "testuser:testpassword"

Request Headers

As well as requiring the authentication header, all requests should include the headers:

Content-Type: application/json
Accept: application/json

List jobs

Request

To list jobs, a GET request is submitted to https://api.melcloud.welcorp.com/api/v1/jobs along with the required headers, which will return a page of the most recent jobs.

Parameters can be passed in to filter the results. These parameters are:

page=## - The page number to return. If not specified, the first page is returned.
page_size=## - The number of records to return in each page of results. Defaults to 10.
job_name={job_name} - Only list jobs with a given job name. For example "Schedule-Reminder", to list jobs given that particular name at creation.
job_type={type} - Only list jobs of the given type, one of "Email", "Fax", "Sms", "2 Way SMS", "Text-to-speech", "2 way TTS", "Voice". The value is case insensitive.
job_status={status} - Only list jobs with a given job status, usually one of: "broadcast submitted", "complete", "closed".
start_after={startdate} - Only list jobs started after the given date and time.
start_before={startdate} - Only list jobs started before the given date and time.
user_id={userid} - Only list jobs belonging to the given userid. Eg. the user with id 987. This is only relevant for authenticated agents or admins.
user_code={usercode} - Only list jobs belonging to the given user_code. Eg. The user with login "au/my_test_account". Only relevant for authenticated agents or admins, as authenticated users can only view their own jobs.

These parameters can be combined, for example to list all jobs of type "Email" with the job name "Schedule-Reminder" for the user with id 987, you would use the URL:

https://api.melcloud.welcorp.com/api/v1/jobs?job_name=Schedule-Reminder&job_type=Email&user_id=987

Response

The response is returned as a JSON object.

All reponses will include a status field, which will reflect the HTTP status code. So a successful response will have a status of 200, and an error will have a status of 4xx or 5xx. This response can be read from the HTTP response status, or the "status" field in the returned JSON.

For a successful response, the JSON will also include a data field, which will contain an array of job objects (See example).

For a unsuccessful response, the JSON will also include an errors field, which will contain a human readable description of the error, such as "errors": "Permission denied"

The JSON will also include counts of the results and a range of navigation links to the various pages.

Click to show the returned field details.

Field	Details
`job_id`	The unique id of the job.
`user_id`	The unique id of the user that created the job.
`user_code`	The user code of the user that created the job.
`job_type`	The type of job, one of "Email", "Fax", "Sms", "2 Way SMS", "Text-to-speech", "2 way TTS", "Voice".
`job_name`	The name of the job, as given when the job was created.
`start_date`	The date and time the job was submitted to the API.
`send_date`	The date and time the job was sent.
`complete_date`	The date and time the job was completed.
`scheduled_date`	The date and time the job was scheduled to be sent.
`total_recipients`	The total number of recipients in the job.
`failed_recipients`	The number of recipients that failed to send.
`sent_recipients`	The number of recipients that were successfully sent to.
`total_amount`	The final cost of the job for all recipients. This will not be set until the job is Complete.
`job_status`	The status of the job, one of "broadcast submitted", "complete", "closed".
`details_url`	The URL to retrieve the details of the job.

Request

https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3

Response

{
  "current_page": 1,
  "data": [
    {
      "job_id": 60276558,
      "user_id": 421,
      "user_code": "au/testuser",
      "job_type": "SMS",
      "job_name": "Quick Send",
      "start_date": "2023-08-29 22:15:57",
      "send_date": "2023-08-29 22:16:02",
      "complete_date": "2023-08-29 22:20:03",
      "scheduled_date": null,
      "total_recipients": 1,
      "failed_recipients": 0,
      "sent_recipients": 1,
      "total_amount": 0.13,
      "job_status": "Complete",
      "details_url": "https://api.melcloud.welcorp.com/api/v1/jobs/60276558"
    },
    {
      "job_id": 60276524,
      "user_id": 421,
      "user_code": "au/testuser",
      "job_type": "SMS",
      "job_name": "Quick Send",
      "start_date": "2023-08-29 22:11:22",
      "send_date": "2023-08-29 22:11:29",
      "complete_date": "2023-09-04 02:05:05",
      "scheduled_date": null,
      "total_recipients": 1,
      "failed_recipients": 0,
      "sent_recipients": 1,
      "total_amount": 0.13,
      "job_status": "Complete",
      "details_url": "https://api.melcloud.welcorp.com/api/v1/jobs/60276524"
    },
    {
      "job_id": 60276514,
      "user_id": 421,
      "user_code": "au/testuser",
      "job_type": "SMS",
      "job_name": "Quick Send",
      "start_date": "2023-08-29 22:08:34",
      "send_date": "2023-08-29 22:09:15",
      "complete_date": "2023-09-04 02:05:05",
      "scheduled_date": null,
      "total_recipients": 1,
      "failed_recipients": 0,
      "sent_recipients": 1,
      "total_amount": 0.218,
      "job_status": "Complete",
      "details_url": "https://api.melcloud.welcorp.com/api/v1/jobs/60276514"
    }
  ],
  "first_page_url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=1",
  "from": 1,
  "last_page": 802,
  "last_page_url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=802",
  "links": [
    {
      "url": null,
      "label": "« Previous",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=1",
      "label": "1",
      "active": true
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=2",
      "label": "2",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=3",
      "label": "3",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=4",
      "label": "4",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=5",
      "label": "5",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=6",
      "label": "6",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=7",
      "label": "7",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=8",
      "label": "8",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=9",
      "label": "9",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=10",
      "label": "10",
      "active": false
    },
    {
      "url": null,
      "label": "...",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=801",
      "label": "801",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=802",
      "label": "802",
      "active": false
    },
    {
      "url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=2",
      "label": "Next »",
      "active": false
    }
  ],
  "next_page_url": "https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=2",
  "path": "https://api.melcloud.welcorp.com/api/v1/jobs",
  "per_page": 3,
  "prev_page_url": null,
  "to": 3,
  "total": 2406,
  "status": 200
}

Get Job Details

Request

To get the full details for a job, a GET request is submitted to https://api.melcloud.welcorp.com/api/v1/jobs/{job_id} along with the required headers, which will return the job details including the original recipient list (if applicable) as well as the delivery reports.

Response

The response will be a Json object with a status element and a data or errors element. The status element reflects the HTTP status, so 200 for success or 4xx/5xx for an error. If the result is an error, then the errors element will contain the error message.

On success, the data element will contain the details of the job, including the original recipient list (if applicable) as well as the delivery reports.

Click to show a list of general report fields. Note though that each job type has slightly different fields, but will match the job creation Json, linked below.

Report fields

Field	Type	Description
`job_id`	Integer	The job_id of the job in question
`user_id`	Integer	The user_id of the user that created the job.
`cost`	Decimal	The base cost per recipient, excluding international or long message charges.
`user_code`	String	The user code of the user that created the job.
`job_type`	String	The type of job, one of "Email", "FAX", "SMS", "2 Way SMS", "Text-to-speech", "2 way TTS", "Voice".
`job_name`	String	The name of the job, as given when the job was created.
`start_date`	String	The date and time the job was submitted to the API. Format is `yyyy-mm-ddThh:mm:ss+timezone offset`. eg. `2023-10-24T12:02:52+11:00`
`send_date`	String	The date and time the job was sent. This is null if the job has not been sent yet. Format it the same as start_date.
`complete_date`	String	The date and time the job was completed. This is null if the job is not yet complete. Format it the same as start_date.
`scheduled_date`	String	The date and time the job was scheduled to be sent. This is null if the job was not scheduled. Format it the same as start_date.
`dedupe`	Integer	Whether the job was deduped to remove duplicate destinations. 0 for no, 1 for yes.
`total_recipients`	Integer	The total number of recipients in the job.
`failed_recipients`	Integer	The number of recipients that failed to send.
`sent_recipients`	Integer	The number of recipients that were successfully sent to.
`total_amount`	Decimal	The final cost of the job for all recipients. This will not be set until the job is Complete.
`total_duration`	Integer	The total duration of the job in seconds. This only applies to Fax, Voice and TTS jobs. This will not be set until the job is Complete.
`job_status`	String	The status of the job, one of 'List Created', 'Pending', 'Queued', 'Broadcast Submitted','JobProcessing', 'Awaiting Reports', 'Complete', 'Closed'.
`manual_sender_id`	String	The sender id used for the job. This is only applicable to SMS and 2 Way SMS jobs.
`recipients`	Array	An array of recipient objects if given in the original job, see "Recipient array fields" in the Create Job - Overview section.
`user_list_ids`	String	A comma separated list of user list ids, if given in the original job..
`reports`	Array	An array of delivery report details, see below.

Delivery report fields

Field	Type	Description
`report_id`	Integer	The internal id of the delviery report
`reference`	String	The reference given for the recipient in the original job.
`recipient`	String	The recipients name given for the recipient in the original job.
`destination`	String	The recipients destination given for the recipient in the original job.
`status`	String	The delivery status code for this recipient. View Fax status codes, View TTS/Voice status codes or View SMS status codes.
`duration`	Integer	For Fax, Voice and TTS jobs, this is the duration of the call in seconds. For SMS jobs, this is the number of sms parts that were used to send a large (>160 characters) sms.
`message_cost`	Decimal	The cost of the message for this recipient.
`stage`	String	This is "Initial" once before the delivery report is recieved, then is it set to "Confirmed".
`notes`	String	Any notes that were added to the delivery report.
`send_date_time`	String	The date and time the message was sent. Format is `yyyy-mm-ddThh:mm:ss+timezone offset`. eg. `2023-10-24T12:02:52+11:00`

Request

https://api.melcloud.welcorp.com/api/v1/jobs?602765583

Response

{
  "data": {
    "job_id": 60276558,
    "user_id": 421,
    "cost": 0.13,
    "user_code": "au/testuser",
    "job_type": "SMS",
    "job_name": "Quick Send",
    "start_date": "2023-08-29T22:15:57+10:00",
    "send_date": "2023-08-29T22:16:02+10:00",
    "complete_date": "2023-08-29T22:20:03+10:00",
    "scheduled_date": null,
    "dedupe": 1,
    "total_recipients": 1,
    "failed_recipients": 0,
    "sent_recipients": 1,
    "total_amount": 0.13,
    "total_duration": 1,
    "job_status": "Complete",
    "manual_sender_id": "+61417914491",
    "recipients": [
      {
        "destination": "0123456789",
        "reference": "Test user",
        "recipient": "Kevin"
      }
    ],
    "user_list_ids": null,
    "message": "sms central test",
    "callback_url": null,
    "additional_report_emails": null,
    "cutoff_hour": null,
    "batch_replies": false,
    "callback_on_sms_status_update": false,
    "reports": [
      {
        "report_id": 139976804,
        "reference": "Test user",
        "recipient": "Kevin",
        "destination": "0123456789",
        "status": "SENT",
        "duration": 1,
        "message_cost": 0.13,
        "stage": "Confirmed",
        "notes": "SenderID: 61417914491./n"
        "send_date_time": "2023-08-29T22:16:05+10:00"
      }
    ]
  },
  "status": 200
}

Create Job - Overview

Jobs are created by posting the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs along with the required headers. While most of the fields (listed below) are consistent across job types, each job type has additional fields (such as message for SMS), as shown in the relevant section below.

You will need to include the basic authentication header outlined above

The response will be a Json object with a status element and a data or errors element. The status element reflects the HTTP status, so 200 for success or 4xx/5xx for an error. If the result is an error, then the errors element will contain the error message.

On success, the data element will contain the job_id for the job.

When sending a job, either an array of recipient details must be included in the field recipients, or a comma separated string of user list ids in the field: user_list_ids, where each user list id is for a list previously uploaded via the portal. If both are included, the message will be sent to the uploaded user lists, and the recipient array will be ignored.

Request fields

Field	Type	Required	Description
`job_type`	String	Yes	The type of job, one of "Email", "Fax", "Sms", "2 Way SMS", "Text-to-speech", "2 way TTS", "Voice".
`job_name`	String	No	The name of the job, as given when the job was created.
`scheduled_date`	DateTime	No	A date time in the future when the message should be sent.
`dedupe`	Integer	No	Whether to remove duplicate recipients from the list. 1 to remove duplicates, 0 to leave them in.
`recipients`	Json array	Dependent	An array of recipient details (see below). This or `user_list_ids` must exist
`user_list_ids`	String	Dependent	A comma separated string of user list ids to send the message to. This or `recipients` must exist
`cutoff_hour`	String	No	This is a time (HH:ss) in your local timezone, past which messaged for this job should not be sent. This can be used to stop large TTS jobs (for example) calling people too late at night.
`callback_url`	String	No	If this is specified for FAX/TTS/Voice jobs, delivery report data is posted to the given url for each recipient delivered to. See the section Fax/TTS Delivery Report Received for the callback details. In addition for SMS jobs, if this is set then SMS replies to two way SMS jobs will be posted to this URL. See the section SMS Reply Received. If the sms specific field `callback_on_sms_status_update` is set to true, then SMS delivery reports will also be posted to this URL. See the section SMS Delivery Report Received.

Note, each message type has it's own additional fields outlined in the relevent section below.

Recipient array fields

Field	Type	Required	Description
`destination`	String	Yes	The destination address for the message. This will be a phone number for Fax voice ir SMS, or an email address for Email.
`reference`	String	No	A reference for the recipient. This will be returned in the delivery reports.
`recipient`	String	No	The name of the recipient. This will be returned in the delivery reports.
`other merge data`	String	No	If your SMS, Email or TTS message includes merge strings like `%%address%%`, you should include an address field here. You can have up to 100 additional different merge fields.

When using pre-uploaded user lists, there are a number of fixed mergefields that are included. These are:
Recipient, Reference, Email, Fax, Phone, Mobile, CustomField1, CustomField2, CustomField3, CustomField4, CustomField5, CustomField6.
Thus when using uploaded lists to send a message, you merge your custom data by including %%recipient%% or %%customfield1%% in your message.

Request

To create a job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "sms",
    "job_name": "My SMS Test",
    "message": "This is a test message to %%recipient%%, with custom fields: %%field1%% and %%field2%%",
    "recipients": [
        {
            "destination": "+123456789",
            "reference": "Main tester",
            "recipient": "Jane Smith",
            "field1": "test value 1a",
            "field2": "test value 1b"
        },
        {
            "destination": "+987654321",
            "reference": "Second Tester",
            "recipient": "John Smith",
            "field1": "test value 2a",
            "field2": "test value 2b"
        },
        
    ]
}

OR

{
    "job_type": "sms",
    "job_name": "My SMS Test to a list",
    "message": "This is a test message to %%recipient%%, with custom fields: %%customfield1%% and %%customfield2%%",
    "user_list_ids": 1234,5678
}

Response

{
  "status": 200,
  "data": 119724
}

OR

{
  "status": 401,
  "errors": "Invalid credentials."
}

Create SMS Job

To create a SMS job, post the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs as outlined above with:
job_type: sms,
but there are three additional fields relevant to SMS jobs.

Additional Request fields

Field	Type	Required	Description
`message`	String	Yes	The message to send as the sms. Note you can include merge fields here, such as `%%recipient%%`.
`manual_sender_id`	String	No	The displayed sender for the job. This can be an alphabetic string up to 11 characters, or a valid mobile number. Note, various carriers put restrictions on what can be used here to limit spoofing other people. Please contact us to make sure your chosen sender id is whitelisted.
`callback_on_sms_status_update`	Boolean	No	If this is set alongside the general field `callback_url`, then on recieving a sms delivery report from the carrier, the delivery report details will be posted to the `callback_url` address. See SMS Delivery Report Received for details.

Request

To create a job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "sms",
    "job_name": "My SMS test",
    "message": "This is a test message to %%recipient%%, with custom fields: %%field1%% and %%field2%%",
    "manual_sender_id": "+61417914491",
    "callback_on_sms_status_update": "https://myserver.com/callback",
    "recipients": [
        {
            "destination": "+123456789",
            "reference": "Main tester",
            "recipient": "Jane Smith",
            "field1": "test value 1a",
            "field2": "test value 1b"
        }
    ]
}

Response

{
  "status": 200,
  "data": 119724
}

Create Two Way SMS Job

You can create a Two Way SMS job, where the recipients can return a reply that will be captured and emailed to you.

This is done by sending a message as outlined above with:
job_type: 2 way sms
and any of the additional fields below:

2 Way SMS Additional Request fields

Field	Type	Required	Description
`message`	String	Yes	The message to send as the sms. Note you can include merge fields here, such as `%%recipient%%`.
`response_email_address`	String	No	The email address to send the replies to.
`optout_code`	String	No	If this is set, any recipient who reply with this code will be added to your optout list and will not be sent further SMSs from your account
`batch_replies`	Boolean	No	If this is set to true, all replies will be batched into a single email, rather than one email per reply.
`expires`	Int	No	This is the time allowed for replies and defaults to 24 hours. After this no more replies will be forwarded to you, though they will still be recorded for the job. Also if `batch_replies` is set to true, the collected replies will be emailed at this point.
`use_two_way_custom_sender_id`	Boolean	No	Normally for a 2 Way SMS the SMS sender id is taken from our pool of sms numbers, or a custom dedicated Sender ID will be used (if configured). This allows replies to be received by our system and recorded. By setting this to true, you can enter a value for `manual_sender_id` and the message will be sent from that sender, but in this case you will have to add to your message something like "Please send replies to %%ReplyNum%%" in your SMS." as otherwise any replies will go to your custom sender id and not our system. Not recommended unless you really need this
`manual_sender_id`	String	No	If `use_two_way_custom_sender_id` is set to true, then the value here will be the displayed sender for the job.
`callback_on_sms_status_update`	Boolean	No	If this is set alongside the general field `callback_url`, then on recieving a sms delivery report from the carrier, the delivery report details will be posted to the `callback_url` address. See SMS Delivery Report Received for details.

Request

To create a 2 way SMS job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "2 way sms",
    "job_name": "My 2 Way SMS test",
    "message": "This is a test message to %%recipient%%, with custom fields: %%field1%% and %%field2%%.  Please reply!",
    "response_email_address" : "smsresponses@mydomain.com",
    "batch_replies" : true,
    "expires" : 48,
    "optout_code" : "STOP",
    "callback_on_sms_status_update": "https://myserver.com/callback",
    "recipients": [
        {
            "destination": "+123456789",
            "reference": "Main tester",
            "recipient": "Jane Smith",
            "field1": "test value 1a",
            "field2": "test value 1b"
        }
    ]
}

Response

{
  "status": 200,
  "data": 119725
}

Create MMS Job (Two Way)

You can create a MMS job including a subject field and a media file, where the recipients can return a reply that will be captured and emailed to you.

This is done by sending a message as outlined above with:
job_type: mms
and any of the additional fields below:

MMS Additional Request fields

Field	Type	Required	Description
`message`	String	No	A text message to send as part of the mms. Note you can include merge fields here, such as `%%recipient%%`.
`subject`	String	No	A Subject field to send as part of the mms. Note you can include merge fields here, such as `%%recipient%%`.
`files`	Json array	Yes	A Json array of the files to send as part of the MMS. This should be a json array of `File` objects (below). These file objects can either contain a url to the file to send or the file content base64 encoded: For example: "files": [ { "name": "textwav1.wav", "url": "https:\/\/mydomain.com\/files\/testwav.wav" }, { "name": "map.jpg", "base64content": "\/9j\/4AAQSkZJRgABAQAAAQABAAD ... 9dUhGzMD0UWAd7PcU8pk44l0xRpGvgihR+gY74DMZjMZgP\/9k=" } ] Note, currently we can only send a single media file via MMS. This will be extended in the future, so we are accepting an array here for future compatibility.
`response_email_address`	String	No	The email address to send the replies to.
`optout_code`	String	No	If this is set, any recipient who reply with this code will be added to your optout list and will not be sent further SMSs from your account
`batch_replies`	Boolean	No	If this is set to true, all replies will be batched into a single email, rather than one email per reply.
`expires`	Int	No	This is the time allowed for replies and defaults to 24 hours. After this no more replies will be forwarded to you, though they will still be recorded for the job. Also if `batch_replies` is set to true, the collected replies will be emailed at this point.
`use_two_way_custom_sender_id`	Boolean	No	Normally for a 2 Way SMS the SMS sender id is taken from our pool of sms numbers, or a custom dedicated Sender ID will be used (if configured). This allows replies to be received by our system and recorded. By setting this to true, you can enter a value for `manual_sender_id` and the message will be sent from that sender, but in this case you will have to add to your message something like "Please send replies to %%ReplyNum%%" in your SMS." as otherwise any replies will go to your custom sender id and not our system. Not recommended unless you really need this
`manual_sender_id`	String	No	If use_two_way_custom_sender_id is set to true, then the value here will be the displayed sender for the job.
`callback_on_sms_status_update`	Boolean	No	If this is set alongside the general field `callback_url`, then on recieving a sms delivery report from the carrier, the delivery report details will be posted to the `callback_url` address. See SMS Delivery Report Received for details.

File

Field	Type	Required	Description
`name`	String	Yes	The file name for the file.
`url`	String	Dependent	The url of the file to download and send. This or `base64content` must be set.
`base64content`	String	Dependent	The base64 encoded content of the file to send. This or `url` must be set.

Request

To create a 2 way SMS job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "2 way sms",
    "job_name": "My 2 Way SMS test",
    "message": "This is a test message to %%recipient%%, with custom fields: %%field1%% and %%field2%%.  Please reply!",
    "response_email_address" : "smsresponses@mydomain.com",
    "batch_replies" : true,
    "expires" : 48,
    "optout_code" : "STOP",
    "callback_on_sms_status_update": "https://myserver.com/callback",
    "recipients": [
        {
            "destination": "+123456789",
            "reference": "Main tester",
            "recipient": "Jane Smith",
            "field1": "test value 1a",
            "field2": "test value 1b"
        }
    ]
}

Response

{
  "status": 200,
  "data": 119725
}

Create Text To Speech Job

To create a TTS job, post the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs as outlined above with:
job_type: tts,
but there are additional fields relevant to TTS jobs.

Additional Request fields

Field Type Required Description

header String No A message to be read out before the main message. This message is NOT repeated, while the main message usually is.

message String Yes The message to be read out. This will generally be repeated twice. The message field can include merge fields such as %%recipient%% to allow customised messages to be read out.

voicemail_message String No An alternate message to be read out if the call goes to voicemail. If not set, the main message will be read out to the recipients voice mail system.

voice

String

No

The voice to use in the TTS conversion. Click to show the available voices.

Voice	Comment
`Allison`	American English, female. Default Voice
`Alan`	Australian English, male
`Grace`	Australian English, female
`Dave`	American English, male
`Steven`	American English, male
`Susan`	American English, female
`Kate`	British English, female
`Simon`	British English, male
`Linlin`	Chinese, female
`Lisheng`	Chinese, female
`Juliette`	French, female
`Charlotte`	Canadian French, female
`Olivier`	Canadian French, male
`Katrin`	German, female
`Italian`	Italian, male
`Esperanza`	Mexican, female
`Felipe`	Brazilian Portuguese, male
`Fernanda`	Brazilian Portuguese, female
`Carlos`	American Spanish, male
`Diego`	Argentine Spanish, male
`Francisca`	Chilian Spanish, female
`Soledad`	American Spanish, female
`Samantha`	British English, female
`Daniel`	British English, male
`Sophie`	Australian English, female
`Chris`	Australian English, male
`Sarah`	American English, female
`Andrew`	American English, male
`Delphine`	Canadian French, female
`Leo`	Canadian French, male
`Marie`	French, female
`Jacques`	French, male
`Camila`	Spanish, female
`Pablo`	Spanish, male
`Isabella`	American Spanish, female
`Luis`	American Spanish, male
`Stefano`	Italian, male
`Ella`	German, female
`Lien`	Mandarin Chinese, female
`Wang`	Mandarin Chinese, male
`Benedita`	Brazilian Portuguese, female
`Francisco`	Brazilian Portuguese, male
`Ahmad`	Arabic, male
`Zara`	Arabic, female

skip_message_repeat Boolean No If this is set to true, the message will not be repeated.

preferred_destination_type String No This should be either Phone or Mobile. If the recipient has a value for both of these in their uploaded list, then this will select which one should be used.

Request

To create a TTS job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type" : "tts",
    "job_name" : "My TTS Test",
    "header" : "This is the header for the test message",
    "message": "This is a main message to %%recipient%%, with custom fields: %%customfield1%% and %%customfield2%%",
    "voicemail_message" => "Sorry we missed you.  This is a test message to %%recipient%%, please get back to us on %%customfield3%%",
    "cutoff_hour" => "18:00",
    "voice" => 'sophie",
    "user_list_ids": 1234,5678
}

Response

{
  "status": 200,
  "data": 119724
}

Create 2 Way Text To Speech Job

To create a 2 Way TTS job, post the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs as outlined above with:
job_type: 2 way tts,
but there are additional fields relevant to 2 Way TTS jobs.

By default, a 2 way TTS job will record the key pressed by the recipient, if any. But additional functionality available is that on a keypress an additional message can be read out, or the call redirected to a phone number of choice. See the two_way_key_responses field below.

Additional Request fields

Field Type Required Description

header String No A message to be read out before the main message. This message is NOT repeated, while the main message usually is.

message String Yes The message to be read out. This will generally be repeated twice. The message field can include merge fields such as %%recipient%% to allow customised messages to be read out.

voicemail_message String No An alternate message to be read out if the call goes to voicemail. If not set, the main message will be read out to the recipients voice mail system.

voice

String

No

The voice to use in the TTS conversion. Click to show the available voices.

Voice	Comment
`Allison`	American English, female. Default Voice
`Alan`	Australian English, male
`Grace`	Australian English, female
`Dave`	American English, male
`Steven`	American English, male
`Susan`	American English, female
`Kate`	British English, female
`Simon`	British English, male
`Linlin`	Chinese, female
`Lisheng`	Chinese, female
`Juliette`	French, female
`Charlotte`	Canadian French, female
`Olivier`	Canadian French, male
`Katrin`	German, female
`Italian`	Italian, male
`Esperanza`	Mexican, female
`Felipe`	Brazilian Portuguese, male
`Fernanda`	Brazilian Portuguese, female
`Carlos`	American Spanish, male
`Diego`	Argentine Spanish, male
`Francisca`	Chilian Spanish, female
`Soledad`	American Spanish, female
`Samantha`	British English, female
`Daniel`	British English, male
`Sophie`	Australian English, female
`Chris`	Australian English, male
`Sarah`	American English, female
`Andrew`	American English, male
`Delphine`	Canadian French, female
`Leo`	Canadian French, male
`Marie`	French, female
`Jacques`	French, male
`Camila`	Spanish, female
`Pablo`	Spanish, male
`Isabella`	American Spanish, female
`Luis`	American Spanish, male
`Stefano`	Italian, male
`Ella`	German, female
`Lien`	Mandarin Chinese, female
`Wang`	Mandarin Chinese, male
`Benedita`	Brazilian Portuguese, female
`Francisco`	Brazilian Portuguese, male
`Ahmad`	Arabic, male
`Zara`	Arabic, female

skip_message_repeat Boolean No If this is set to true, the message will not be repeated.

preferred_destination_type String No This should be either Phone or Mobile. If the recipient has a value for both of these in their uploaded list, then this will select which one should be used.

two_way_key_responses

Json array

No

This provides the ability to play additional messages on recipient keypress, or redirect the recipient call to a number of your choice.
If not used, the key pressed will be recorded but no additional action taken.
If used, this should be a json array of 2 Way Keypress objects (below). For example:

"two_way_key_responses": [
        {
            "key_press": "1",
            "redirect_to": "6987654321",
            "response_message": "Thanks, you're being redirected"
        },
        {
            "key_press": "2",
            "response_message": "Thanks, you're NOT being redirected"
        },
        {
            "key_press": "3",
            "redirect_to": "6987654322"
        }
    ]

2 Way Keypress fields

Field	Type	Required	Description
`key_press`	Integer	Yes	The key pressed that causes the `response_message` and/or `redirect_to` action.
`response_message`	String	No	The message to read out if the key is pressed.
`redirect_to`	String	No	The number to connect the call to if the key is pressed

Request

To create a 2 way TTS job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "2 way tts",
    "job_name": "2 way tts test",
    "header": "This is the header for the test message",
    "message": "This is a test message to %%recipient%%, with custom fields: %%field1%% and %%field2%%",
    "voicemail_message": "This is a test message to %%recipient%%, with custom fields: %%field1%% and %%field2%%",
    "cut_off_hour": "18:00",
    "recipients": [
        {
            "destination": "+33677680275",
            "reference": "Jon test",
            "recipient": "Jon A",
            "field1": "value1",
            "field2": "value2"
        }
    ],
    "two_way_key_responses": [
        {
            "key_press": "1",
            "redirect_to": "6987654321",
            "response_message": "Thanks, you're being redirected"
        },
        {
            "key_press": "2",
            "response_message": "Thanks, you're NOT being redirected"
        },
        {
            "key_press": "3",
            "redirect_to": "6987654322"
        }
    ]
}

Response

{
  "status": 200,
  "data": 119724
}

Create FAX Job

To create a FAX job, post the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs as outlined above with:
job_type: fax,
but there are two additional fields relevant to FAX jobs listed below.

The total file size for faxes should not exceed 20MB, and the supported file types are jpg, tif, png, gif, doc, docx, xls, xlsx, pdf, txt, ppt, pptx, pdfx.

Additional Request fields

Field	Type	Required	Description
`use_high_resolution`	Boolean	No	If true, then the fax will be sent in "High Resolution"
`files`	Json array	Yes	A Json array of the files to fax. This should be a json array of `File` objects (below). These file objects can either contain a url to the file to fax or the file content base64 encoded: For example: "files": [ { "name": "textfax1.doc", "url": "https:\/\/mydomain.com\/files\/test_file.doc" }, { "name": "map.jpg", "base64content": "\/9j\/4AAQSkZJRgABAQAAAQABAAD ... rMTrmc8FLrTRwXYU9dUhGzMD0UWAd7PcU8pk44l0xRpGvgihR+gY74DMZjMZgP\/9k=" } ]

File

Field	Type	Required	Description
`name`	String	Yes	The file name for the file.
`url`	String	Dependent	The url of the file to download and send. This or `base64content` must be set.
`base64content`	String	Dependent	The base64 encoded content of the file to send. This or `url` must be set.

Request

To create a job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "fax",
    "job_name": "My FAX test",
    "use_high_resolution": true,
    "callback_on_sms_status_update": "https://myserver.com/callback",
    "use_high_resolution": true,
    "recipients": [
        {
            "destination": "+123456789",
        }
    ],
    "files": [
        {
            "name": "textfax1.doc",
            "url": "https:\/\/mydomain.com\/files\/test_file.doc"
        },
        {
            "name": "map.jpg",
            "base64content": "\/9j\/4AAQSkZJRgABAQAAAQABAAD
            ...
            ...
            ... rMTrmc8FLrTRwXYU9dUhGzMD0UWAd7PcU8pk44l0xRpGvgihR+gY74DMZjMZgP\/9k="
        }
    ]
}

Response

{
  "status": 200,
  "data": 119724
}

Create EMAIL Job

To create an Email job, post the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs as outlined above with:
job_type: email,
but there are additional fields relevant to Email jobs.

The total file size for all attachments is 20MB.

Additional Request fields

Field	Type	Required	Description
`subject`	String	No	The subject of the email to be sent. This can be merged with the list data. For example `subject: Schedule for %%recipient%%`
`html_message`	String	Dependent	The html content of the email. This or the `text_message`, or both must have a value. This can be merged with the list data. For example `html_message: "<p>Hi %%recipient%%, ...</p>"`
`text_message`	String	Dependent	The plain text content of the email. This or the `html_message`, or both must have a value. This can be merged with the list data. For example `html_message: "Hi %%recipient%%, ..."`
`from_name`	String	No	The name of the email sender
`from_email`	String	Yes	The email address of the sender
`attachments`	Json array	No	A Json array of files to email. This should be a json array of `File` objects (below). These file objects can either contain a url to the file to email or the file content base64 encoded: For example: "attachments": [ { "name": "textfax1.doc", "url": "https:\/\/mydomain.com\/files\/test_file.doc" }, { "name": "map.jpg", "base64content": "\/9j\/4AAQSkZJRgABAQAAAQABAAD ... rMTrmc8FLrTRwXYU9dUhGzMD0UWAd7PcU8pk44l0xRpGvgihR+gY74DMZjMZgP\/9k=" } ]

File

Field	Type	Required	Description
`name`	String	Yes	The file name for the file.
`url`	String	Dependent	The url of the file to download and send. This or `base64content` must be set.
`base64content`	String	Dependent	The base64 encoded content of the file to send. This or `url` must be set.

Request

To create an Email job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "email",
    "job_name": "email test",
    "subject": "email test subject",
    "html_message": "<html><body><h1>Hi %%recipient%%<h1> <p>This is a test message.<\/p>",
    "text_message": "Hi %%recipient%%\nThis is the text version of a test message",
    "from_name": "Jane Test",
    "from_email": "janetest@mymail.com",
    "user_list_ids": 1234,5678
    "attachments": [
        {
            "name": "my test doc.pdf",
            "url": "https:\/\/mydomain.com\/download\/test_doc_v2.pdf"
        },
        {
            "name": "map.jpg",
            "base64content": "\/9j\/4AAQSkZJRgABAQAAAQABAAD ...
            ...
            ...
            ...Ad7PcU8pk44l0xRpGvgihR+gY74DMZjMZgP\/9k="
        }
    ]
}

Response

{
  "status": 200,
  "data": 119724
}

Create Voice Job

To create a Voice job, post the job data as a JSON string to https://api.melcloud.welcorp.com/api/v1/jobs as outlined above with:
job_type: voice,
but there are additional fields relevant to Voice jobs below.

The Maximum file size for voice messages is 4000000MB, and the supported file type is wav.

Additional Request fields

Field	Type	Required	Description
`preferred_destination_type`	String	No	This should be either `Phone` or `Mobile`. If the recipient has a value for both of these in their uploaded list, then this will select which one should be used.
`attachments`	Json array	No	A Json array of files to email. This should be a json array of `File` objects (below). These file objects can either contain a url to the file to email or the file content base64 encoded: For example: "audiofile": { "name": "voicemessage.wav", "url": "https:\/\/mydomain.com\/download\/voicefile_v2.wav" },

File

Field	Type	Required	Description
`name`	String	Yes	The file name for the file.
`url`	String	Dependent	The url of the file to download and send. This or `base64content` must be set.
`base64content`	String	Dependent	The base64 encoded content of the file to send. This or `url` must be set.

Request

To create a voice job, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/jobs

with content type = application/json and the basic authentication header

{
    "job_type": "voice",
    "job_name": "test voice",
    "audiofile": {
        "name": "voicemessage.wav",
        "url": "https:\/\/mydomain.com\/download\/voicefile_v2.wav"
    },
    "recipients": [
        {
            "destination": "+123456789",
        }
    ]
}

Response

{
  "status": 200,
  "data": 119724
}

List users

Request

To list users, a GET request is submitted to https://api.melcloud.welcorp.com/api/v1/users along with the required headers, which will return a page of users. Authorized admins can see all uses for a distributor, agents can see all users linked to them, and a user will only see themself.

A parameter can be passed in to find users with full or partial name matches, as well as parameters to pick different pages:

page=## - The page number to return. If not specified, the first page is returned.
page_size=## - The number of records to return in each page of results. Defaults to 10.
user_code={usercode} - Only list users who's name matches *{usercode}*. For example "jon" will find "au/jon1", "au/jonathan" etc.

Response

The response is an array of users returned as a JSON object.

All reponses will include a status field, which will reflect the HTTP status code. So a successful response will have a status of 200, and an error will have a status of 4xx or 5xx. This response can be read from the HTTP response status, or the "status" field in the returned JSON.

For a successful response, the JSON will also include a data field, which will contain an array of matched users.

For a unsuccessful response, the JSON will also include an errors field, which will contain a human readable description of the error, such as "errors": "Permission denied"

The JSON will also include counts of the results and a range of navigation links to the various pages, unless the requester is the user themselves, then it will only show the users details.

Click to show the returned field details.

User details

Field Details Required for Create

user_id The users User ID. No

company_id The Company ID for the company that the user is linked to. No

agent_id The Agent Id, if any, that the user is linked to. No

dist_id the Distributor ID that the user is linked to. No

account_type This will be Credit (pre paid) or Acct (post paid account). Yes

user_code The user code (login username) for this user. Yes

title Users title. No

first_name Users first name. Yes

last_name Users last name. Yes

email Users email. Yes

phone Users phone/landline. No

fax Users fax. No

mobile Users mobile. No

user_live Is the user live. Yes

additional_reports_address Additional email addresses for reports. No

report_type The report type, either "Summary" or "Detailed". No

timezone_id

Timezone id Click to show the timezones.

Timezone iD	Timezone
1	albania
2	algeria
195	american samoa
3	andorra
4	angola
5	anguilla
6	antarctica
7	antigua and barbuda
9	argentina western province
8	argentina
10	armenia
11	aruba
12	ascension island
14	australia aest
18	australia western australia
15	australia northern territory
17	australia south australia
16	australia queensland
13	australia lord howe island
19	austria
263	azerbaijan
21	bahamas
22	bahrain
23	bangladesh
24	barbados
25	belarus
26	belgium
27	belize
28	benin
29	bermuda
30	bhutan
31	bolivia
32	botswana
33	brazil acre
36	brazil west
35	brazil east
34	brazil atlantic islands
38	brunei
39	bulgaria
40	burkina faso
41	burundi
42	cambodia
43	cameroon
49	canada yukon & pacific
47	canada mountain
45	canada central
46	canada eastern
44	canada atlantic
48	canada newfoundland
52	cayman islands
53	chad
56	chile
57	china
58	colombia
60	cook islands
61	costa rica
62	croatia
63	cuba
64	cyprus
65	czech republic
66	denmark
67	djibouti
68	dominica
70	ecuador
71	egypt
72	el salvador
73	equatorial guinea
74	eritrea
75	estonia
76	ethiopia
77	falkland islands
78	fiji
79	finland
80	france
81	french guiana
82	french polynesia
83	gabon
84	gambia
85	georgia
86	germany
87	ghana
88	greece
91	greenland thule
89	greenland
90	greenland scoresbysun
92	grenada
93	guadeloupe
94	guam
95	guatemala
97	guyana
98	haiti
99	honduras
100	hong kong
101	hungary
102	iceland
103	india
106	indonesia west
104	indonesia central
105	indonesia east
107	iran
108	iraq
109	ireland
110	israel
111	italy
112	ivory coast
113	jamaica
114	japan
115	jordan
116	kazakhstan
117	kenya
118	kiribati
121	kuwait
122	kyrgyzstan
123	laos
124	latvia
125	lebanon
126	lesotho
127	liberia
128	libya
129	lithuania
130	luxembourg
131	macedonia
132	madagascar
134	malawi
135	malaysia
136	maldives
137	mali
138	malta
165	mariana island
140	marshall islands
141	martinique
142	mauritania
143	mauritius
144	mayotte
146	mexico baja calif norte
147	mexico nayarit sinaloa sonora
145	mexico
148	moldova
149	monaco
150	mongolia
151	morocco
152	mozambique
153	namibia
155	nepal
156	netherlands
158	new caledonia
159	new zealand
160	nicaragua
161	niger
163	niue
164	norfolk island
119	north korea
167	norway
168	oman
169	pakistan
170	palau
171	panama
172	papua new guinea
173	paraguay
174	peru
175	philippines
176	poland
177	portugal
178	puerto rico
179	qatar
181	reunion
182	romania
188	russia zone one
192	russia zone three
193	russia zone two
186	russia zone four
185	russia zone five
190	russia zone six
189	russia zone seven
183	russia zone eight
187	russia zone nine
191	russia zone ten
184	russia zone eleven
194	rwanda
212	saint helena
213	saint kitts and nevis
214	saint lucia
216	saint vincent grenadines
197	san marino
199	saudi arabia
200	senegal
203	seychelles
204	sierra leone
205	singapore
206	slovenia
207	solomon islands
208	somalia
209	south africa
120	south korea
210	spain
211	sri lanka
217	sudan
218	swaziland
219	sweden
220	switzerland
221	syria
222	taiwan
224	tanzania
225	thailand
226	togo
227	tonga
228	trinidad and tobago
229	tunisia
230	turkey
231	turkmenistan
233	tuvalu
234	uganda
235	united arab emirates
54	united kingdom channel islands
236	united kingdom
238	united kingdom northern ireland
237	united kingdom new hebrides
239	uruguay
245	america hawaii
241	america aleutian
240	america alaska
248	america pacific
242	america arizona
247	america mountain
244	america eastern
246	america indiana east
243	america central
249	uzbekistan
250	vanuatu
252	venezuela
253	vietnam
256	wallis and futuna islands
257	yemen
261	zambia
262	zimbabwe

No

monthly_limit Spending limit for the month. No

agree_spam_policy Has this user agreed to the spam policy. Yes

user_added The date the user was added. No

receive_reports Does this user want job reports. No

show_recipients_in_email_report Should the recipients be hidden in emailed job reports. No

show_recipients_in_online_report Should the recipients be hidden in online job reports. No

hide_costs_in_reports Should the reports include costs? (Yes/No) No

fax_header_text Text to show in the header of outgoing faxes. No

call_back_url A URL to POST delivery report data to. Note this can also be set per job. No

default_tts_voice The default TTS voice to user for TTS jobs if not otherwise specified in the job. No

tts_repeat_count Default number of times to repeat the main TTS message. No

default_voice_caller_id Default caller ID to user when making voice/TTS calls. No

default_sms_sender_id Default sender ID to user when sending SMSs. No

etob_authentication_type Authentication type for Email to Broadcast jobs. One of "None", "Password" or "ChResp" (Challange Response). See separate "Email To Broadcast" documentation for details. No

etob_email_address Email to broadcast sender address. Alternate Email to broadcast sender address. See separate "Email To Broadcast" documentation for details. No

etob_subject_behaviour What to do with the subject field of incoming Email To Broadcast requests. See separate "Email To Broadcast" documentation for details. No

etob_use_email_body_as_fax_cover For Email to Fax, should the body of the email be sent as an initial fax page. No

etob_email_message_start_string Text before this in the message is ignored. No

etob_email_message_start_string_include If etob_email_message_start_string is used, then should that text be included in the final message. No

etob_email_message_end_string Text after and including this in the message is ignored. No

etob_strip_non_ascii Strip out non ascii from incoming emails. For example to send a simple ascci SMS. No

etob_disabled Disable sending jobs through Email to Broadcast. No

etob_xheader_code If a value is given here, then instead of identifying the user by the email's FROM address, the system instead looks for the email header field "x-etobcode:{etob_xheader_code}". No

etob_ip_whitelist Only emails that passed through ip addresses listed here will be accepted for this user. Separate multiple IP addresses with commas. eg: 123.123.123.123, 234.234.234.234 No

etob_ip_whitelist_alert_address Address to send alerts to if EtoB jobs come in from the wrong IP address. No

email_address_for_inbound_fax If Inbound Faxing is setup for this user, then this is the address that inbound faxes will be sent to. No

credit_limit_for_alert For credit users, send an alert when available credit drops below this value. No

credit_limit_alert_address Address to send the Credit Limit alerts to. No

hide_accounts Do not let users view accounting details. No

filter_non_ascii_in_sms When sending SMSs, automatically strip out any non-ascii characters. No

tts_max_character_limit Limit the amount of characters that the TTS system will read out. No

default_sms_reply_email_address The default address that 2 Way SMSs will send reply information to. No

tts_message_prefix Code to be added before at the start of a TTS message. Usually used for speaking speed commands. No

maximum_document_retention_hours Number of hours that received documents will be kept after job completion before being deleted. No

include_fax_content_in_reports Whether to include a copy of any outbound faxes in the job reports. No

company array of company details linked to this user. No

Company details

Field	Details	Required for Create
`company_id`	The company ID.	No
`dist_id`	The companies linked distributor ID.	Yes
`agent_id`	The companies linked agent ID.	No
`name`	The company name.	Yes
`abn`	The company ABN.	No
`address`	The companies street address.	Yes
`suburb`	The companies suburb.	Yes
`state`	The companies state.	Yes
`postcode`	The companies postcode.	Yes
`country`	The companies country.	Yes
`billing_user_id`	The id of the user who get's the invoices. *If blank, details below must be filled in.	No*
`billing_contact_title`	The title of the person that will get the invoices.	No*
`billing_contact_surname`	The surname of the person that will get the invoices.	No*
`billing_contact_first_name`	The first name of the person that will get the invoices.	No*
`billing_contact_phone`	The phone number of the person that will get the invoices.	No
`billing_contact_fax`	The fax number of the person that will get the invoices.	No
`billing_contact_email`	The email of the person that will get the invoices.	No*

Request

https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3

Response

{
    "current_page": 1,
    "data": [
        {   
            "user_id": 123,
            "company_id": 456,
            "agent_id": 789,
            "dist_id": 1,
            "account_type": "Acct",
            "user_code": "au/testuser",
            "title": null,
            "first_name": "Jane",
            "last_name": "Smith",
            "email": "jsmith@mydomain.com",
            "phone": "0312323434",
            "fax": "0355667788",
            "mobile": "0487 654 432",
            "user_live": true,
            "additional_reports_address": "test@ts.com",
            "report_type": "Detailed",
            "timezone_id": 17,
            "monthly_limit": 8888,
            "agree_spam_policy": 1,
            "user_added": "2004-08-27 16:32:28",
            "receive_reports": true,
            "show_recipients_in_email_report": true,
            "show_recipients_in_online_report": true,
            "fax_header_text": null,
            "call_back_url": null,
            "default_tts_voice": null,
            "tts_repeat_count": null,
            "default_voice_caller_id": null,
            "default_sms_sender_id": null,
            "etob_authentication_type": null,
            "etob_email_address": null,
            "etob_subject_behaviour": null,
            "etob_use_email_body_as_fax_cover": false,
            "etob_email_message_start_string": null,
            "etob_email_message_start_string_include": false,
            "etob_email_message_end_string": null,
            "etob_strip_non_ascii": false,
            "etob_disabled": false,
            "etob_xheader_code": null,
            "etob_ip_whitelist": null,
            "etob_ip_whitelist_alert_address": null,
            "email_address_for_inbound_fax": null,
            "credit_limit_for_alert": null,
            "credit_limit_alert_address": null,
            "hide_costs_in_reports": false,
            "hide_accounts": false,
            "filter_non_ascii_in_sms": false,
            "tts_max_character_limit": null,
            "default_sms_reply_email_address": null,
            "tts_message_prefix": null,
            "maximum_document_retention_hours": null,
            "include_fax_content_in_reports": false,
            "company": {
                "company_id": 1,
                "dist_id": 1,
                "agent_id": 91,
                "name": "Generic Computer Corp",
                "abn": null,
                "address": "321 Test street",
                "suburb": "Melbourne",
                "state": "VIC",
                "postcode": "3456",
                "country": "Australia",
                "billing_user_id": 123,
                "billing_contact_title": null,
                "billing_contact_surname": null,
                "billing_contact_first_name": null,
                "billing_contact_phone": null,
                "billing_contact_fax": null,
                "billing_contact_email": null
            }
        },
        {...},
        {...},
            
    ],
    "first_page_url": "https://api.melcloud.welcorp.com/api/v1/users?page=1",
    "from": 1,
    "last_page": 46,
    "last_page_url": "https://api.melcloud.welcorp.com/api/v1/users?page=46",
    "links": [
        {
        "url": null,
        "label": "« Previous",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=1",
        "label": "1",
        "active": true
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=2",
        "label": "2",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=3",
        "label": "3",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=4",
        "label": "4",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=5",
        "label": "5",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=6",
        "label": "6",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=7",
        "label": "7",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=8",
        "label": "8",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=9",
        "label": "9",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=10",
        "label": "10",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=45",
        "label": "45",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=46",
        "label": "46",
        "active": false
        },
        {
        "url": "https://api.melcloud.welcorp.com/api/v1/users?page=2",
        "label": "Next »",
        "active": false
        }
    ],
    "next_page_url": "https://api.melcloud.welcorp.com/api/v1/users?page=2",
    "path": "https://api.melcloud.welcorp.com/api/v1/users",
    "per_page": 10,
    "prev_page_url": null,
    "to": 10,
    "total": 457,
    "status": 200
}

View User

Request

To view a single user, a GET request is submitted to https://api.melcloud.welcorp.com/api/v1/users/{user_id} along with the required headers.

Response

The response is a JSON object with a status field, which will reflect the HTTP status code, and a data or errors field.

A successful response will have a status of 200, and an error will have a status of 4xx or 5xx. This response can be read from the HTTP response status, or the "status" field in the returned JSON.

For a successful response, the data field will contain a json object with the details of the user.

For a unsuccessful response, the errors field will contain a human readable description of the error, such as "errors": "Permission denied"

Click to show the returned field details.

Request

https://api.melcloud.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3

Response

{
    "status": 200,
    "data": {
        "user_id": 123,
        "company_id": 456,
        "agent_id": 789,
        "dist_id": 1,
        "account_type": "Acct",
        "user_code": "au/testuser",
        "title": null,
        "first_name": "Jane",
        "last_name": "Smith",
        "email": "jsmith@mydomain.com",
        "phone": "0312323434",
        "fax": "0355667788",
        "mobile": "0487 654 432",
        "user_live": true,
        "additional_reports_address": "test@ts.com",
        "report_type": "Detailed",
        "timezone_id": 17,
        "monthly_limit": 8888,
        "agree_spam_policy": 1,
        "user_added": "2004-08-27 16:32:28",
        "receive_reports": true,
        "show_recipients_in_email_report": true,
        "show_recipients_in_online_report": true,
        "fax_header_text": null,
        "call_back_url": null,
        "default_tts_voice": null,
        "tts_repeat_count": null,
        "default_voice_caller_id": null,
        "default_sms_sender_id": null,
        "etob_authentication_type": null,
        "etob_email_address": null,
        "etob_subject_behaviour": null,
        "etob_use_email_body_as_fax_cover": false,
        "etob_email_message_start_string": null,
        "etob_email_message_start_string_include": false,
        "etob_email_message_end_string": null,
        "etob_strip_non_ascii": false,
        "etob_disabled": false,
        "etob_xheader_code": null,
        "etob_ip_whitelist": null,
        "etob_ip_whitelist_alert_address": null,
        "email_address_for_inbound_fax": null,
        "credit_limit_for_alert": null,
        "credit_limit_alert_address": null,
        "hide_costs_in_reports": false,
        "hide_accounts": false,
        "filter_non_ascii_in_sms": false,
        "tts_max_character_limit": null,
        "default_sms_reply_email_address": null,
        "tts_message_prefix": null,
        "maximum_document_retention_hours": null,
        "include_fax_content_in_reports": false,
        "company": {
            "company_id": 1,
            "dist_id": 1,
            "agent_id": 91,
            "name": "Generic Computer Corp",
            "abn": null,
            "address": "321 Test street",
            "suburb": "Melbourne",
            "state": "VIC",
            "postcode": "3456",
            "country": "Australia",
            "billing_user_id": 123,
            "billing_contact_title": null,
            "billing_contact_surname": null,
            "billing_contact_first_name": null,
            "billing_contact_phone": null,
            "billing_contact_fax": null,
            "billing_contact_email": null
        }
    }

}

Add / Edit User

Request

To add a single user, a POST request is submitted to https://api.melcloud.welcorp.com/api/v1/users with the authentication header and a json object representing the new user.

To edit and existing user, a PUT request is submitted to https://api.melcloud.welcorp.com/api/v1/users/{user_id} with the authentication header and a json object representing the changes to the user record.

Response

The response is a JSON object with a status field, which will reflect the HTTP status code, and a data or errors field.

A successful response will have a status of 200, and an error will have a status of 4xx or 5xx. This response can be read from the HTTP response status, or the "status" field in the returned JSON.

For a successful response, the data field will contain the new or updated user id.

For a unsuccessful response, the errors field will contain a human readable description of the error, such as "errors": "Permission denied"

Click to show the field details.

Create Request

Send a POST request to

https://api.melcloud.welcorp.com/api/v1/users

with a json object representing the new user.

{
    "user_code": "au/mytestuser",
    "password": "Test Password",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jsmith@test.com",
    "fax": "6987654321",
    "mobile": "6123456789",
    "account_type": "Acct",
    "agree_spam_policy": true,
    "company": {
        "name": "test company",
        "abn": "123456789",
        "address": "123 test st",
        "suburb": "testville",
        "state": "NSW",
        "postcode": "2345",
        "country": "Australia"
    }
}

Or if there is an existing company to join:

{
    "user_code": "au/mytestuser",
    "company_id": 123,
    "password": "Test Password",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jsmith@test.com",
    "fax": "6987654321",
    "mobile": "6123456789",
    "account_type": "Acct",
    "agree_spam_policy": true,
}

Update Request

Send a PUT request to

https://api.melcloud.welcorp.com/api/v1/users/{user_id}

with a json object representing the changes to the user.

{
    "email": "mynewemail@test.com",
    "phone": "6876765654",
}

Response

Both update and create requests will return a similar response.

{
  "status": 200,
  "data": 123
}

Or

{
  "status": 422,
  "errors": "Validation failed: The user_code has already been taken."
}

Callback on Fax, TTS and Voice Delivery Report

If the job field callback_url has a valid URL, then on completion of delivery to a Fax, Voice or TTS recipient, then a POST request will be sent to that URL with the below fields.

Note, this callback is a separate system to this API, and sends a standard html POST request with the content type application/x-www-form-urlencoded, not json data.

Fax, Voice, TTS Callback POST fields

Field	Type	Description
`BroadcastID`	Integer	The job_id of the job sending to the recipient
`Timestamp`	String	This is the delivery timestamp in ISO_OFFSET_DATE_TIME format (milliseconds are always 0). i.e. `yyyy-mm-ddThh:mm:ss+timezone offset`. eg. `2023-10-24T12:02:52+11:00`
`Reference`	String	The reference given to this recipient in the API request or uploaded list.
`Recipient`	String	The name given to this recipient in the API request or uploaded list.
`Destination`	String	The recipient's phone number
`Status`	String	The delivery status of the message. View Fax status codes or View TTS/Voice status codes.
`Duration`	Integer	The duration of the call in seconds.
`Cost`	Float	The cost of the message.
`Keypress`	Integer	The keypress that the recipient pressed, if any.
`Voicemail`	Boolean	Whether the call went to voicemail. Only applicable for Voice and TTS messages.
`BroadcastName`	String	The name of the job sending to the recipient

Post message


                            Headers: Content type: application/x-www-form-urlencoded
                            POST FIELDS:

                            BroadcastID=62131644

                            Timestamp=2023-10-24T12:02:52+11:00

                            Reference=Customer 123

                            Recipient=Jane Smith

                            Destination=61498765432

                            Status=SENT

                            Duration=57

                            Cost=0.76

                            Keypress=1

                            Voicemail=false

                            BroadcastName=Quick+Send

Callback on SMS Reply Received.

If the field callback_url has a valid URL, then on receipt of a SMS reply to an outgoing Two Way SMS job, a POST request will be sent to that URL with the below fields.

Note, this callback is a separate system to this API, and sends a standard html POST request with the content type application/x-www-form-urlencoded, not json data.

SMS reply Callback POST fields

Field	Type	Description
`BroadcastID`	Integer	The job_id of the job sending to the recipient
`Timestamp`	String	This is the delivery timestamp in ISO_OFFSET_DATE_TIME format (milliseconds are always 0). i.e. `yyyy-mm-ddThh:mm:ss+timezone offset`. eg. `2023-10-24T12:02:52+11:00`
`Reference`	String	The reference given to this recipient in the API request or uploaded list.
`Recipient`	String	The name given to this recipient in the API request or uploaded list.
`Destination`	String	The recipient's phone number
`Response`	String	The text of the message that the recipient replied with.
`BroadcastName`	String	The name of the job sending to the recipient

Post message


                            Headers: Content type: application/x-www-form-urlencoded
                            POST FIELDS:

                            BroadcastID=62131644

                            Timestamp=2023-10-24T12:02:52+11:00

                            Reference=Customer 123

                            Recipient=Jane Smith

                            Destination=61498765432

                            Response=This+is+a+reply

                            BroadcastName=Quick+Send

Callback on SMS Delivery Report.

If the field callback_url has a valid URL, and the field callback_on_sms_status_update is set to true, then on receipt of a SMS delivery report, then a POST request will be sent to that URL with the below fields.

Note, this callback is a separate system to this API, and sends a standard html POST request with the content type application/x-www-form-urlencoded, not json data.

SMS reply Callback POST fields

Field	Type	Description
`BroadcastID`	Integer	The job_id of the job sending to the recipient
`Timestamp`	String	This is the delivery timestamp in ISO_OFFSET_DATE_TIME format (milliseconds are always 0). i.e. `yyyy-mm-ddThh:mm:ss+timezone offset`. eg. `2023-10-24T12:02:52+11:00`
`Reference`	String	The reference given to this recipient in the API request or uploaded list.
`Recipient`	String	The name given to this recipient in the API request or uploaded list.
`Destination`	String	The recipient's phone number
`Status`	String	The status of the delivery to the recipient. View SMS status codes
`BroadcastName`	String	The name of the job sending to the recipient

Post message


                            Headers: Content type: application/x-www-form-urlencoded
                            POST FIELDS:

                            BroadcastID=62131644

                            Timestamp=2023-10-24T12:02:52+11:00

                            Reference=Customer 123

                            Recipient=Jane Smith

                            Destination=61498765432

                            Status=SENT

                            BroadcastName=Quick+Send

Client Validation/Two Factor Authentication(2FA) system.

This system is a simple REST interface to send and validate Two Factor Authentication codes.

The 2FA codes can be sent via SMS, Email or Text To Speech messages. By default, codes are valid for up to 30 minutes after sending (but can be set as valid up to 5 hours), and any code sent in this window will be accepted, so if the user sends one code to their phone and another to their email, either code will work

This feature is comprised of two functions: sendCode, and validateCode outlined below.

Send 2FA Code

To initiate a 2FA message send, Either POST an appropriate json block to https://api.melcloud.welcorp.com/api/v1/client_verification/sendCode with content type = application/json and the basic authentication header

Or you can send a simple GET query with the parameters as part of the URL. The basic authentication header is required.

Request fields

Field	Type	Required	Description
`client_ref`	String	Yes	A unique reference for this client. This will be matched in the `validateCode` step to identify the user.
`message_type`	String	Yes	One of `sms`, `email` or `tts`.
`message_destination`	String	Yes	For SMS, this should be a valid international mobile number, including the country code. eg `61987654321`. For Email, this should be a valid email address. For TTS, this should be a valid international phone number, including the country code. eg `61987654321`.
`message_template`	String	Dependent	A template of the message to be sent, including the string `[[code]]` in the place where the generated code will be inserted. eg. `Your verification code to log into TEST COMPANY is [[code]]` This field OR `company_name` is required.
`company_name`	String	Dependent	If `message_template` is not provided, a `company_name` is required to be inserted into the default template: `Your [[company_name]] verification code is [[code]]`

Response

The response will be a Json object with a status element and a data or errors element. The status element reflects the HTTP status, so 200 for success or 4xx/5xx for an error.

On success, the data element will contain the string message sent, or if the result is an error, then the errors element will contain an array of the error messages.

Click the Show Example button at the top right of this section to see a sample request and response.

Validate 2FA Code

To validate a users entered 2FA code, either POST an appropriate json block to https://api.melcloud.welcorp.com/api/v1/client_verification/validateCode with content type = application/json and the basic authentication header

Or you can send a simple GET query with the parameters as part of the URL. The basic authentication header is required.

Request fields

Field	Type	Required	Description
`client_ref`	String	Yes	The unique reference for this client used when sending the 2FA request.
`entered_code`	String	Yes	The code entered by the user to be compared to the one sent earlier by the `sendCode` function.
`validation_window`	Integer	No	The length of time in minutes that codes are valid to be used. This can be between 1 minutes and 120 minutes. Default value is 10 minutes

Response

The response will be a Json object with a status element and a data or errors element. The status element reflects the HTTP status, so 200 for success or 4xx/5xx for an error.

If there are no errors, the data element will contain the string valid, or invalid depending on if the right code was entered. If the result is an error, then the errors element will contain an array of the error messages.

Click the Show Example button at the top right of this section to see a sample request and response.

Send 2FA message example

To initiate a 2FA message send, POST an appropriate json block to

https://api.melcloud.welcorp.com/api/v1/client_verification/sendCode

with content type = application/json and the basic authentication header

{
    "client_ref" => "user-123",
    "message_type" => "sms",
    "message_destination" => '61987654321',
    "message_template" => "Your test copany auth no. is [[code]]"
}

Or send a Get Reqeust:

https://api.melcloud.welcorp.com/api/v1/client_verification/sendCode?client_ref=user-123&message_type=sms&message_destination=61987654321&message_template=Your+test+copany+auth+no.+is+[[code]]

With the basic authentication header

Response to 2FA Send request

{
  "status": 200,
  "data": 'message sent'
}

OR

{
  "status": 401,
  "errors": "Invalid credentials."
}

Verify 2FA code example

To validate the code entered by the user, POST an appropriate json block containing the client_ref and entered_code to

https://api.melcloud.welcorp.com/api/v1/client_verification/validateCode

with content type = application/json and the basic authentication header

{
    "client_ref" => "user-123",
    "entered_code" => "987654",
}

Or send a Get Reqeust:

https://api.melcloud.welcorp.com/api/v1/client_verification/validateCode?client_ref=user-123&entered_code=987654

With the basic authentication header

Response to 2FA validation request

{
  "status": 200,
  "data": 'invalid'
}

OR

{
  "status": 401,
  "errors": "Invalid credentials."
}

Field	Description
`SENT`	Fax was successfully sent.
`BUSY`	Line gave busy signal with all retries. The receiving fax machine was busy.
`NOAN`	Phone keeps ringing. Nobody answers. If you are sure that the number is correct, please contact the recipient. There may be a problem with their fax machine (e.g. out of paper).
INVD	The number is not a valid number. Please check the number and dial again.
NOLN	Problem with phone line. Please check line.
BARR	Wrong number (number changed, call barred).
OPTO	Number opted out.
NSUP	Service or Function not supported by network or user.
COLL	At the moment we started trying to send a fax a call came in.
ERR	Procedural or unknown error.
FAIL	Document conversion failed. Please resubmit your document.
NOFX	No fax machine detected. Please check the number and try again.
PAGC	No confirmation received after last page transmitted. The fax may have been received by the recipient and the machine failed to confirm.
BADC	Bad connection or fax modem error at receiving end.
HNUP	Call disconnected by the network or remote user (reason unspecified).
LDTE	Latest Delivery timeout expired.

SENT	Message was successfully sent.
BSIN	Line busy or incorrect number.
MGNC	Receipt of message not confirmed.
RJCT	The message has been rejected.
ERR	Procedural or unknown error.
HNUP	Call disconnected by the network or remote user (reason unspecified).
NOLN	Problem with phone line. Please check line.
NOAN	Phone keeps ringing. Nobody answers.
LDTE	Latest Delivery timeout expired.
OPTO	Destination opted out.

SENT	Message was successfully sent.
QUED	Message queued for delivery.
FAIL	Message couldn't be delivered, destination unavailable.
RECE	Error in destination number, please check the number.
SVRE	Error in the SMS delivery pathway, delivery failed.
BARR	Destination blocked or forbidden.
INVN	The number is not a valid number. Please check the number and dial again.
BADS	The sender ID is invalid.
EXPD	The message could not be deliverd in the requested delivery period.
OPTO	Destination opted out.

Rest API

Table Of Contents

Authentication & Headers

List jobs

Submit jobs

Manage Users

Callbacks

Other Functions

Authentication

Request Headers

List jobs

Request

Response

Request

Response

Get Job Details

Request

Response

Report fields

Delivery report fields

Request

Response

Create Job - Overview

Request fields

Recipient array fields

Request

Response

Create SMS Job

Additional Request fields

Request

Response

Create Two Way SMS Job

2 Way SMS Additional Request fields

Request

Response

Create MMS Job (Two Way)

MMS Additional Request fields

File

Request

Response

Create Text To Speech Job

Additional Request fields

Request

Response

Create 2 Way Text To Speech Job

Additional Request fields

2 Way Keypress fields

Request

Response

Create FAX Job

Additional Request fields

File

Request

Response

Create EMAIL Job

Additional Request fields

File

Request

Response

Create Voice Job

Additional Request fields

File

Request

Response

List users

Request

Response

User details

Company details

Request

Response

View User

Request

Response

Request

Response

Add / Edit User

Request

Response

Create Request