Rest API

V1.01

This Rest API allows a registered user to submit a variety of messages and retrieve reports using PUT, GET and POST over HTTP.

It also allows Admins or Agents to add and edit users, as well as view the jobs of their users.

There are two primary resources: Jobs and Users

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.welcorp.com/api/v1/jobs -H "Authorization: Basic bG9naW46cGFzc3dvcmQ"
or
curl https://api.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.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.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.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.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.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.welcorp.com/api/v1/jobs/60276514"
    }
  ],
  "first_page_url": "https://api.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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.welcorp.com/api/v1/jobs?job_type=sms&start_after=2023-04-07&page_size=3&page=2",
  "path": "https://api.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.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.

Request

https://api.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.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.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.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.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.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.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.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
AllisonAmerican English, female. Default Voice
AlanAustralian English, male
GraceAustralian English, female
DaveAmerican English, male
StevenAmerican English, male
SusanAmerican English, female
KateBritish English, female
SimonBritish English, male
LinlinChinese, female
LishengChinese, female
JulietteFrench, female
CharlotteCanadian French, female
OlivierCanadian French, male
KatrinGerman, female
ItalianItalian, male
EsperanzaMexican, female
FelipeBrazilian Portuguese, male
FernandaBrazilian Portuguese, female
CarlosAmerican Spanish, male
DiegoArgentine Spanish, male
FranciscaChilian Spanish, female
SoledadAmerican Spanish, female
SamanthaBritish English, female
DanielBritish English, male
SophieAustralian English, female
ChrisAustralian English, male
SarahAmerican English, female
AndrewAmerican English, male
DelphineCanadian French, female
LeoCanadian French, male
MarieFrench, female
JacquesFrench, male
CamilaSpanish, female
PabloSpanish, male
IsabellaAmerican Spanish, female
LuisAmerican Spanish, male
StefanoItalian, male
EllaGerman, female
LienMandarin Chinese, female
WangMandarin Chinese, male
BeneditaBrazilian Portuguese, female
FranciscoBrazilian Portuguese, male
AhmadArabic, male
ZaraArabic, 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.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.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
AllisonAmerican English, female. Default Voice
AlanAustralian English, male
GraceAustralian English, female
DaveAmerican English, male
StevenAmerican English, male
SusanAmerican English, female
KateBritish English, female
SimonBritish English, male
LinlinChinese, female
LishengChinese, female
JulietteFrench, female
CharlotteCanadian French, female
OlivierCanadian French, male
KatrinGerman, female
ItalianItalian, male
EsperanzaMexican, female
FelipeBrazilian Portuguese, male
FernandaBrazilian Portuguese, female
CarlosAmerican Spanish, male
DiegoArgentine Spanish, male
FranciscaChilian Spanish, female
SoledadAmerican Spanish, female
SamanthaBritish English, female
DanielBritish English, male
SophieAustralian English, female
ChrisAustralian English, male
SarahAmerican English, female
AndrewAmerican English, male
DelphineCanadian French, female
LeoCanadian French, male
MarieFrench, female
JacquesFrench, male
CamilaSpanish, female
PabloSpanish, male
IsabellaAmerican Spanish, female
LuisAmerican Spanish, male
StefanoItalian, male
EllaGerman, female
LienMandarin Chinese, female
WangMandarin Chinese, male
BeneditaBrazilian Portuguese, female
FranciscoBrazilian Portuguese, male
AhmadArabic, male
ZaraArabic, 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.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.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.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.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.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.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.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.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.

Request

https://api.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.welcorp.com/api/v1/users?page=1",
    "from": 1,
    "last_page": 46,
    "last_page_url": "https://api.welcorp.com/api/v1/users?page=46",
    "links": [
        {
        "url": null,
        "label": "« Previous",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=1",
        "label": "1",
        "active": true
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=2",
        "label": "2",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=3",
        "label": "3",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=4",
        "label": "4",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=5",
        "label": "5",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=6",
        "label": "6",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=7",
        "label": "7",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=8",
        "label": "8",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=9",
        "label": "9",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=10",
        "label": "10",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=45",
        "label": "45",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=46",
        "label": "46",
        "active": false
        },
        {
        "url": "https://api.welcorp.com/api/v1/users?page=2",
        "label": "Next »",
        "active": false
        }
    ],
    "next_page_url": "https://api.welcorp.com/api/v1/users?page=2",
    "path": "https://api.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.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.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.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.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.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.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.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.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.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.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.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.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."
}