Get authenticated using your application credentials
Firstly, you should get your application credentials (application-id, application-secret) from the Routee Platform and on the applications menu.
Then you should encode the application-id:application-secret string to a Base64 string.
Having this string you are now able to exchange your application credentials for an access token by calling the endpoint.
The Authorization header of the request must include the word Basic followed by the encoded string.
Important! All tokens that are issued from Routee's authorization server are valid for 1 hour.
That means that once you get an HTTP response with a status code of 401, from any Routee API resource, you should issue a new token and repeat your request with the new token.
Each application is associated with an Account that belongs to the user. Any requests that are made using an access token from an application are the same as if they were made by the associated account.
RESPONSE PARAMETERS
access_token
The generated access_token. This must be used in all requests.
token_type
Token_type ("Bearer") is a parameter in Access Token generate call to Authorization server.
expires_in
Time in seconds that the token will expire. The token is set by default to expire in 1 hour (3600 seconds).
scope
The requested scopes.
permissions
The permissions granted to the authenticated application.
ERROR CODES
For possible error responses see here
Send an SMS
Sending a single SMS is one of the most common tasks performed on the Routee Platform. Sending a message is as simple as POST-ing to the SMS resource. This is a paid service. For pricing check here
Live Preview
Your message will be sent!
RESPONSE PARAMETERS
trackingId
The tracking id used to identify the message.
createdAt
The date that this resource was created.
from
The sender Id of the message.
to
The phone number the message is about to be sent to.
body
The message you sent.
status
The status of the SMS. Check here for possible values.
label
The label that was given to the SMS.
bodyAnalysis
The analysis for the body of the SMS.
bodyAnalysis.characters
The total number of characters of the message body.
bodyAnalysis.parts
The number of actual SMS that will be sent.
bodyAnalysis.transcode
Contains information for the transcoded body of the SMS message. This will be available only if the message can be transcoded.
bodyAnalysis.transcode.message
The transcoded message of the original unicode message.
bodyAnalysis.transcode.parts
The number of the parts of the transcoded message.
bodyAnalysis.unicode
Indicates if the body contains unicode characters.
bodyAnalysis.unsupportedGSMCharacters
Which characters caused the message to be considered as unicode.
flash
Indicates if the message is flash SMS.
callback
Defines the notification callback information for an individual SMS message. You can also set this value from Routee Dev Platform on the Applications menu.
callback.url
The URL that Routee will POST to, each time your message status changes to one of the following: Queued, Failed, Sent, Unsent, Delivered, or Network Error. When Routee POSTs back to your service, a HTTP 200 OK response must be returned. If Routee doesn't receive a 200 OK response, it will try to POST again (up to 5 times).
callback.strategy
When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
ttl
The duration in minutes the delivery of an SMS will be attempted. If the SMS is not delivered within the validity period, then the SMS status will be "Undelivered", with "detailedStatus": "Expired"
ERROR CODES
400
400001009
You don't have enough balance to send the SMS.
400
400005000
The sender id is invalid.
400
400000000
Validation Error.
A required field is missing.
Invalid value of a field.
401
You are unauthorized.
Invalid access token, maybe has expired.
403
403000000
Access denied.
Your application's access token does not have the right to use SMS service.
Callback - SMS Delivery reports
Notifications you receive about the status of your messages.
Example:
POST http://www.yourserver.com/sms-delivery-reports
The following parameters are sent in as delivery reports - callback.
When you send an SMS, you have to set the "callback" parameter in order to receive notification when the delivery status of an SMS changes.
Your callback service will receive a POST HTTP request with the following request body:
{
"messageId":"string",
"smsId":"string",
"campaignTrackingId":"string",
"part":"number",
"parts":"number",
"label":"string",
"to":"string",
"from":"string",
"country":"string",
"operator":"string",
"groups":[
"string"
],
"campaignName":"string",
"status":{
"name":"string",
"reason":{
"detailedStatus":"string",
"description":"string"
},
"updatedDate":"string"
},
"message":"string",
"applicationName":"string",
"latency":"number",
"price":"number",
"direction":"string",
"originatingService":"string"
}
PARAMETERS:
messageId
The trackingId of the SMS (all the parts of a multipart SMS have the same messageId).
smsId
The unique id of each SMS part included in a message. If the message is multipart then these values will be different for each part.
campaignTrackingId
The trackingId of the campaign (if the SMS was sent using the /SMS/campaign resource).
part
The number of the current SMS part.
parts
The total number of SMS parts.
label
A generic label used for tagging the SMS.
to
The recipient of the SMS message (in E.164 format).
from
The senderId of the SMS message.
country
The country of the recipient.
operator
The operator of the recipient.
groups
All contact groups (tags) that this contact belongs to.
campaignName
The name of the SMS Campaign (if the SMS was part of a campaign).
status
The full status object of the SMS message.
status.name
The status name of the SMS message.
status.updatedDate
The date of the last status change of the SMS.
status.reason
The reason of the status.
status.reason.detailedStatus
The detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation.
status.reason.description
The description of the detailed status.
message
The message that was sent.
applicationName
The name of the application that was used to send this message.
latency
The overall delivery latency of the message.
price
The cost of the SMS.
direction
The direction of the SMS.
originatingService
The service that sent this message.
See details about SMS callbacks here Callbaks (WebHooks)
Inbound SMS
Receive inbound messages
Example:
POST https://www.yourserver.com/inbound-sms
When you rent a number, you have to set the callback Url ("inboundSmsCallbackUrl") in order to receive the inbound messages.
Your callback service will receive a POST HTTP request with the following request body:
{
"messageId": string,
"from": string,
"to": string,
"message": string,
"parts": integer,
"originatingService": "Sms",
"direction": "Inbound",
"receivedDate": string
}
Parameters:
messageId
The id of the inbound message.
from
The sender of the inbound message.
to
The recipient of the inbound message (your number).
message
The body of the inbound message.
parts
The message's total parts.
originatingService
The originating service of the message (SMS).
direction
The direction of the message (Inbound).
receivedDate
The date that the inbound message was received (ISO format).
See details about the Inbound SMS here: Inbound Messages (MO)
Analyse an SMS message
Analysing an SMS is useful when the user needs information about the message before actually sending it.
Response Parameters
bodyAnalysis
The analysis for the body of the SMS.
bodyAnalysis.characters
The total number of characters of the message body.
bodyAnalysis.parts
The number of actual message parts (concatenated or not - more information about concadenated messages here that will be sent.
bodyAnalysis.transcode
Contains information for the transcoded body of the sms message. This will be available only if the message can be transcoded.
bodyAnalysis.transcode.message
The transcoded message of the original unicode message.
bodyAnalysis.transcode.parts
The number of the parts of the transcoded message.
bodyAnalysis.unicode
Indicates if the body contains unicode characters.
bodyAnalysis.unsupportedGSMCharacters
Which characters caused the message to be considered as unicode.
cost
The cost of the message per part
Supported Unicode Languages
Transcoding is available for Greek, French, Italian and German locales.
ERROR CODES
404
404001001
Account not found.
Send Bulk Messages - Campaigns
Routee allows to send messages to multiple recipients/contacts/groups. This is a paid service. For pricing check here
RESPONSE PARAMETERS
trackingId
The tracking id used to identify the campaign.
createdAt
The date that this resource was created.
type
The service type of the campaign.
scheduledDate
The time the campaign is scheduled to run.
campaignName
The name of the campaign.
from
The sender of the message.
to
The phone numbers the message is about to be sent to.
body
The message you sent.
state
The state of the campaign.
statuses
Defines the number of SMS per message status. Either, Queued, Sent, Unsent, Failed, Delivered, Undelivered. Check here for more information
smsAnalysis
The data analysis the this SMS.
smsAnalysis.contacts
The details for each contact. The key refers to the id of the contact given in the request.
smsAnalysis.contacts.recipient
The mobile phone that corresponds to the given contact id.
smsAnalysis.contacts.recipientCountry
The country that corresponds to the given contact id.
smsAnalysis.contacts.blacklisted
Indicates if the contact is in the blacklist. If true the contact will be excluded from the request.
smsAnalysis.numberOfRecipients
The total number of recipients.
smsAnalysis.recipientCountries
The country that each mobile belongs to. The key refers to the mobile of the recipients request property
smsAnalysis.recipientsPerCountry
The total recipients per country. The key refers to the country.
smsAnalysis.recipientsPerGroup
For each group the number of recipients that it contains without the blacklisted contacts (in SMS blacklist). The key refers to the group given in the group request property.
smsAnalysis.totalInGroups
The total number of recipients in all given groups excluding the ones already specified (in contacts and recipients request property) as well as the ones that are blacklisted.
smsAnalysis.bodyAnalysis
The analysis for the body of the SMS.
smsAnalysis.bodyAnalysis.characters
The total number of characters of message body.
smsAnalysis.bodyAnalysis.parts
The number of actual SMS that will be sent.
smsAnalysis.bodyAnalysis.transcode
Contains information for the transcoded body of the SMS message. This will be available only if the message can be transcoded.
smsAnalysis.bodyAnalysis.transcode.message
The transcoded message of the original unicode message.
smsAnalysis.bodyAnalysis.transcode.parts
The number of the parts of the transcoded message.
smsAnalysis.bodyAnalysis.unicode
Indicates if the body contains unicode characters.
smsAnalysis.bodyAnalysis.unsupportedGSMCharacters
Which characters caused the message to be considered as unicode.
flash
Indicates if the message is a flash SMS.
respectQuietHours
Indicates if the SMS should respect the quiet hours.
callback
Defines the notification callback information for an individual SMS message
callback.url
The URL that Routee will POST to, each time your message status changes to one of the following: Queued, Failed, Sent, Unsent, Delivered, or Network Error. When Routee POSTs back to your service, a HTTP 200 OK response must be returned. If Routee doesn't receive a 200 OK response, it will try to POST again (up to 5 times)
callback.strategy
When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion)
campaignCallback
Defines the notification callback information for the progress of the SMS campaign.
campaignCallback.url
The URL that Routee will POST to, each time your campaign status changes to one of the following: Scheduled, Queued, Sent, Running, Finished, or Failed. When Routee POSTs back to your service, a HTTP 200 OK response must be returned. If Routee doesn't receive a 200 OK response, it will try to POST again (up to 5 times).
campaignCallback.strategy
When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
reminder
Defines the recipients that will receive a test SMS before the actual SMS is sent.
reminder.minutesBefore
The minutes before the scheduled date (that the SMS will be sent) for the test SMS to be sent.
reminder.to
The recipients that will get the test SMS before the campaign will start. Must be a list with valid mobile numbers starting with “ + ” and the country code.
contacts
The contacts in the account selected as recipients.
groups
The groups of contacts in the account selected as recipients.
fallbackValues
Defines the default values in case a contact does not contain any of the selected personalized labels. The key refers to the label name.
ttl
The duration in minutes the delivery of an SMS will be attempted. If the SMS is not delivered within the validity period, then the SMS status will be "Undelivered", with "detailedStatus": "Expired"
errors.code
The code of error
errors.developerMessage
Message of error
errors.property
The numbers of invalid recipients
ERROR CODES
400
400001009
You don't have enough balance to send the campaign.
400
400005000
The sender id is invalid (errorCode: 002), or you haven't specified any recipients (errorCode: 004) or the recipient numbers are not valid mobile numbers (errorCode: 008).
Keep in mind that If your recipients (either in "to", "groups" or "contacts" array) contain at least one invalid number, then the bulk send out will not be dispatched.
Try to exclude the invalid recipients in order your campaign to be sent.
409
409009003
Your account already has a campaign with the given name.
400
400009004
Your campaign has no recipients. Your groups might be empty or all contacts might be blacklisted.
404
404002001
A contact id does not exist.
Analyze Bulk Messages - Campaigns
Analyzing a bulk sendout is useful when the user needs information about the send out before actually sending it.
RESPONSE PARAMETERS
contacts
The details for each contact. The key refers to the id of the contact given in the request.
contacts.recipient
The mobile phone that corresponds to the given contact id.
smsAnalysis.contacts.recipientCountry
The country that corresponds to the given contact id.
contacts.blacklisted
Indicates if the contact is in the SMS blacklist. If true the contact will be excluded from the request.
numberOfRecipients
The total number of recipients.
recipientCountries
The country that each mobile belongs to. The key refers to the mobile of the recipients request property.
recipientsPerCountry
The total recipients per country. The key refers to the country.
recipientsPerGroup
For each group the number of recipients that it contains without the blacklisted contacts (in SMS blacklist). The key refers to the group given in the group request property.
totalInGroups
The total number of recipients in all given groups excluding the ones already specified (in contacts and recipients request property) as well as the ones that are blacklisted.
bodyAnalysis
The analysis for the body of the SMS.
bodyAnalysis.characters
The total number of characters of message body.
bodyAnalysis.parts
The number of actual SMS that will be sent.
bodyAnalysis.transcode
Contains information for the transcoded body of the sms message. This will be available only if the message can be transcoded.
bodyAnalysis.transcode.message
The transcoded message of the original unicode message.
bodyAnalysis.transcode.parts
The number of the parts of the transcoded message.
bodyAnalysis.unicode
Indicates if the body contains unicode characters.
bodyAnalysis.unsupportedGSMCharacters
Which characters caused the message to be considered as unicode.
errors.code
The code of error
errors.developerMessage
Message of error
errors.property
The numbers of invalid recipients
ERROR CODES
400
400001009
You don't have enough balance to send the campaign.
400
400005000
In case you haven't specified any recipients or the sender is invalid.
409
409009003
Your account already has a campaign with the given name.
400
400009004
Your campaign has no recipients. Your groups might be empty or all contacts might be blacklisted.
404
404002001
A contact id does not exist.
Track an SMS
You can get all the tracking information for the messages (parts) of a single SMS by providing its message id.
RESPONSE PARAMETERS
applicationName
The name of the application that was used to send this message.
campaign
The name of the campaign that this message was sent from.
country
The country of the recipient in ISO 3166-1 alpha 2 format.
smsId
The unique id of one SMS part included in the message. If the message is multipart then these values will be different for each part.
messageId
The id of the message (trackingId). All the parts of a multipart SMS have the same messageId.
groups
The groups that the recipient belongs to.
body
The message of the SMS.
operator
The operator of the recipient.
originatingService
The service that sent this message.
to
The recipient.
latency
The overall delivery latency of the message.
parts
The number of actual SMS parts.
part
The number of the current SMS part.
price
The cost of this SMS part.
label
The label of the SMS tracking.
status
Information about the Sms status.
status.date
The date that the status was reported.
status.status
The status of the SMS tracking. Check here for possible values.
status.reason
The reason of the status
status.reason.detailedStatus
The detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation.
Check here for details.
status.reason.description
The description of the detailed status
from
The sender Id of the message
direction
The direction of the message. Possible values: "Inbound", "Outbound"
ERROR CODES
404
404005000
Tracking not found.
Track multiple messages for a specific bulk send out - campaign
You can get all the tracking information for the messages of a bulk send out by providing the tracking id
RESPONSE PARAMETERS
totalPages
The number of total pages.
last
Whether the current page is the last one.
totalElements
The total amount of elements for the current search.
first
Whether the current page is the first one.
numberOfElements
The number of elements currently on this page.
number
The requested page number.
size
The requested page size.
content
Contains the search results.
content.applicationName
The name of the application that was used to send this message.
content.campaignName
The name of the campaign that this message was sent from.
content.campaignTrackingId
The tracking id of the campaign that this message was sent from.
content.country
The country of the recipient in ISO 3166-1 alpha 2 format.
content.smsId
The unique id of one SMS part included in the message. If the message is multipart then these values will be different for each part.
content.messageId
The id of the message. All the parts of a multipart SMS have the same messageId.
content.groups
The groups that the recipient belongs to.
content.body
The message of the SMS.
content.operator
The operator of the recipient.
content.originatingService
The service that sent this message.
content.to
The recipient.
content.latency
The overall delivery latency of the message.
content.parts
The number of actual SMS parts.
content.part
The number of the current SMS part.
content.price
The cost of this SMS part.
content.status
Information about the Sms status.
content.status.date
The date that the status was reported.
content.status.status
The status of the SMS. Check here for possible values.
content.status.reason
The reason of the status
content.status.reason.detailedStatus
The detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation.
Check here for details.
content.status.reason.description
The description of the detailed status
content.from
The sender Id of the message
content.direction
The direction of the message. Possible values: "Inbound", "Outbound"
ERROR CODES
404
404001001
Account not found.
400
404009001
Campaign not found.
Track multiple messages with filters for a specific time range
Limit the tracking result of multiple sms by passing filters (accept a date range only for the latest 7 days).
RESPONSE PARAMETERS
totalPages
The number of total pages.
last
Whether the current page is the last one.
totalElements
The total amount of elements for the current search.
first
Whether the current page is the first one.
numberOfElements
The number of elements currently on this page.
number
The requested page number.
size
The requested page size.
content
Contains the search results.
content.applicationName
The name of the application that was used to send this message.
content.campaignName
The name of the campaign that this message was send from.
content.campaignTrackingId
The tracking id of the campaign that this message was sent from.
content.country
The country of the recipient in ISO 3166-1 alpha 2 format.
content.smsId
The unique id of one SMS part included in a message. If the message is multipart then these values will be different for each part.
content.messageId
The id of the message. All the parts of a multipart SMS have the same messageId.
content.groups
The groups that the recipient belongs to.
content.body
The message of the SMS.
content.operator
The operator of the recipient.
content.originatingService
The service that sent this message.
content.to
The recipient.
content.latency
The overall delivery latency of the message.
content.parts
The number of actual SMS parts.
content.part
The number of the current SMS part.
content.price
The cost of this SMS part.
content.label
The label that was given to the SMS tracking.
content.status
Information about the Sms status.
content.status.date
The date that the status was reported.
content.status.status
The status of the SMS. Check here for possible values.
content.status.reason
The reason of the status
content.status.reason.detailedStatus
The detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation.
Check here for details.
content.status.reason.description
The description of the detailed status
content.from
The sender Id of the message
content.direction
The direction of the message. Possible values: "Inbound", "Outbound"
content.receivedDate
The date that an inbound message has received.
ERROR CODES
404
404001001
Account not found.
400
404009001
Campaign not found.
Retrieve the countries that are supported by Quiet Hours feature
RESPONSE PARAMETERS
code
The country code in ISO 3166-1 alpha-2 format (US, GR).
name
The country name translated in the requested language.
localeName
The country name translated in its native language (for Greece it will be Ελλάδα).
isoA3Code
The country code in ISO 3166-1 alpha-3 format (USA, GRC).
supported
Indicates if the country is supported by the quiet hours feature.
ERROR CODES
404
404001001
Account not found.
Update a scheduled bulk send out - campaign
Update an already scheduled campaign. You can change the recipients or the sender id or any other parameter you set previously. Note that the campaign must have status "Scheduled" in order to update it.
Request/Response Parameters Description
See /sms/campaign for explanation of the request/response parameters
Caution
If you don't include the "scheduledDate" parameter in your request then your campaign will be sent immediately.
ERROR CODES
404
404009001
The campaign with the given tracking id doesn't exist.
400
400009002
The campaign status is not Scheduled.
400
400001009
You don't have enough balance to send the campaign.
400
400005000
In case you haven't specified any recipients or the sender is invalid.
409
409009003
Your account already has a campaign with the given name.
400
400009004
Your campaign has no recipients. Your groups might be empty or all contacts might be blacklisted.
404
404002001
A contact id does not exist.
Delete a scheduled bulk send out - campaign
When you no longer want to send an already scheduled bulk send out - campaign, deleting it is very simple.
ERROR CODES
404
404009001
The campaign with the given tracking id doesn't exist.
400
400009002
The campaign status is not Scheduled.
Retrieve details for a bulk send out - campaign
You can retrieve the details of a specific bulk send out - campaign by its tracking id.
RESPONSE PARAMETERS
trackingId
The tracking id used to identify the campaign.
createdAt
The date that this resource was created.
type
The service type of the campaign.
scheduledDate
The time the campaign is scheduled to run.
campaignName
The name of the campaign.
from
The sender of the message.
to
The phone numbers the message is about to be sent to.
body
The message you sent.
state
The state of the campaign.
statuses
Defines the number of SMS per message status. Either, Queued, Sent, Unsent, Failed, Delivered, Undelivered. For more details check here
smsAnalysis
The data analysis the this SMS.
smsAnalysis.contacts
The details for each contact. The key refers to the id of the contact given in the request.
smsAnalysis.contacts.recipient
The mobile phone that corresponds to the given contact id.
smsAnalysis.contacts.recipientCountry
The country that corresponds to the given contact id.
smsAnalysis.contacts.blacklisted
Indicates if the contact is in the SMS blacklist. If true the contact will be excluded from the request.
smsAnalysis.numberOfRecipients
The total number of recipients.
smsAnalysis.recipientCountries
The country that each mobile belongs to. The key refers to the mobile of the recipients request property
smsAnalysis.recipientsPerCountry
The total recipients per country. The key refers to the country.
smsAnalysis.recipientsPerGroup
For each group the number of recipients that it contains without the blacklisted contacts (in SMS blacklist). The key refers to the group given in the group request property.
smsAnalysis.totalInGroups
The total number of recipients in all given groups excluding the ones already specified (in contacts and recipients request property) as well as the ones that are blacklisted.
smsAnalysis.bodyAnalysis
The analysis for the body of the SMS.
smsAnalysis.bodyAnalysis.characters
The total number of characters of message body.
smsAnalysis.bodyAnalysis.parts
The number of actual SMS that will be sent.
smsAnalysis.bodyAnalysis.transcode
Contains information for the transcoded body of the SMS message. This will be available only if the message can be transcoded.
smsAnalysis.bodyAnalysis.transcode.message
The transcoded message of the original unicode message.
smsAnalysis.bodyAnalysis.transcode.parts
The number of the parts of the transcoded message.
smsAnalysis.bodyAnalysis.unicode
Indicates if the body contains unicode characters.
smsAnalysis.bodyAnalysis.unsupportedGSMCharacters
Which characters caused the message to be considered as unicode.
flash
Indicates if the message is a flash SMS.
respectQuietHours
Indicates if the SMS should respect the quiet hours.
campaignCallback
Defines the notification callback information for the progress of the SMS campaign.
campaignCallback.url
The URL that Routee will POST to, each time your campaign status changes to one of the following: Scheduled, Queued, Sent, Running, Finished, or Failed.
For more details check here
campaignCallback.strategy
When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
reminder
Defines the recipients that will receive a test SMS before and/or after the actual SMS is sent.
reminder.minutesAfter
The minutes after the scheduled date (that the SMS will be sent) that the test SMS will be sent.
reminder.minutesBefore
The minutes before the scheduled date (that the SMS will be sent) that the test SMS will be sent.
reminder.to
The recipients that will get the test SMS before and/or after the campaign will start. Must be a list with valid mobile numbers starting with “ + ” and the country code.
contacts
The contacts in the account selected as recipients.
groups
The groups of contacts in the account selected as recipients.
fallbackValues
Defines the default values when the SMS has labels, in case a contact does not contain any of these labels. The key refers to the label name.
ERROR CODES
404
404009001
The campaign with the given tracking id doesn't exist.
View all the available numbers
RESPONSE PARAMETERS
totalPages
The number of total pages.
last
Whether the current page is the last one.
totalElements
The total amount of elements for the current search.
first
Whether the current page is the first one.
numberOfElements
The number of elements currently on this page.
number
The requested page number.
size
The requested page size.
content
Contains the search results.
content.msisdn
The phone number.
content.country
The country code in ISO 3166-1 alpha-2 format.
content.services
The supported services.
content.inboundCosts
Information about inbound message costs.
content.inboundCosts.price
The price per inbound message.
content.inboundCosts.currency
The currency of the price.
content.inboundCosts.service
The service that the inbound message price is referred to.
content.monthlyCosts
Information about costs per month.
content.monthlyCosts.price
The cost of the number per month.
content.monthlyCosts.currency
The currency of the price.
content.activationCosts
Information about activation costs.
content.activationCosts.price
The activation cost of the number.
content.activationCosts.currency
The currency of the price.
content.chargeInterval
The time interval used for charging the inbound calls (in seconds).
content.tollFree
Whether the number is Toll-Free.
View all the available numbers with filters
RESPONSE PARAMETERS
totalPages
The number of total pages.
last
Whether the current page is the last one.
totalElements
The total amount of elements for the current search.
first
Whether the current page is the first one.
numberOfElements
The number of elements currently on this page.
number
The requested page number.
size
The requested page size.
content
Contains the search results.
content.msisdn
The msisdn (the phone number).
content.country
The country code in ISO 3166-1 alpha-2 format.
content.services
The supported services.
content.inboundCosts
Information about inbound message costs.
content.inboundCosts.price
The price per inbound message.
content.inboundCosts.currency
The currency of the price.
content.inboundCosts.service
The service that the inbound message price is referred to.
content.monthlyCosts
Information about costs per month.
content.monthlyCosts.price
The cost of the number per month.
content.monthlyCosts.currency
The currency of the price.
content.activationCosts
Information about activation costs.
content.activationCosts.price
The activation cost of the number.
content.activationCosts.currency
The currency of the price.
content.chargeInterval
The time interval used for charging the inbound calls (in seconds).
content.tollFree
Whether the number is Toll-Free.
Rent a Number
RESPONSE PARAMETERS
trackingId
The trackingId of the number.
msisdn
The phone number. Format with a '+' and country code e.g., +3069485xxxxx (E.164 format).
country
The country code in ISO 3166-1 alpha-2 format.
services
The supported services.
inboundCosts
Information about inbound message costs.
inboundCosts.price
The price per number inbound message.
inboundCosts.currency
The currency of the price.
inboundCosts.service
The service that the inbound message price is referred to.
monthlyCosts
Information about costs per month.
monthlyCosts.price
The cost of the number per month.
monthlyCosts.currency
The currency of the price.
activationCosts
Information about activation costs.
activationCosts.price
The activation cost of the number.
activationCosts.currency
The currency of the price.
inboundSmsCallbackUrl
The defined callback URL that will receive the inbound messages.
voiceInboundStrategy
Represents the voice inbound strategy.
voiceInboundStrategy.dialplanUrl
The defined dialplan URL.
inboundVoiceCallbackUrl
The defined callback URL that will receive the inbound voice messages.
nextRenewal
The datetime of the next monthly cost charging.
chargeInterval
The time interval used for charging the inbound calls (in seconds).
tollFree
Whether the number is Toll-Free.
Update a Number
RESPONSE PARAMETERS
trackingId
The trackingId of the number.
msisdn
The phone number. Formated with a '+' and country code e.g., +3069485xxxxx (E.164 format).
country
The country code in ISO 3166-1 alpha-2 format.
services
The supported services.
inboundCosts
Information about inbound message costs.
inboundCosts.price
The price per inbound message.
inboundCosts.currency
The currency of the price.
inboundCosts.service
The service that the inbound message price is referred to.
monthlyCosts
Information about costs per month.
monthlyCosts.price
The cost of the number per month.
monthlyCosts.currency
The currency of the price.
activationCosts
Information about activation costs.
activationCosts.price
The activation cost of the number.
activationCosts.currency
The currency of the price.
inboundSmsCallbackUrl
The defined callback URL that will receive the inbound messages.
voiceInboundStrategy
Represents the voice inbound strategy.
voiceInboundStrategy.dialplanUrl
The defined dialplan URL.
inboundVoiceCallbackUrl
The defined callback URL that will receive the inbound voice messages.
nextRenewal
The date that the msisdn will automatically renew at.
View all your numbers
RESPONSE PARAMETERS
totalPages
The number of total pages.
last
Whether the current page is the last one.
totalElements
The total amount of elements for the current search.
first
Whether the current page is the first one.
numberOfElements
The number of elements currently on this page.
number
The requested page number.
size
The requested page size.
content
Contains the search results.
content.trackingId
The tracking id of the number.
content.msisdn
The msisdn (the phone number).
content.country
The country code in ISO 3166-1 alpha-2 format.
content.services
The supported services.
content.inboundCosts
Information about inbound message costs.
content.inboundCosts.price
The price per inbound message.
content.inboundCosts.currency
The currency of the price.
content.inboundCosts.service
The service that the inbound message price is referred to.
content.monthlyCosts
Information about costs per month.
content.monthlyCosts.price
The cost of the per month.
content.monthlyCosts.currency
The currency of the price.
content.activationCosts
Information about activation costs.
content.activationCosts.price
The activation cost of the number.
content.activationCosts.currency
The currency of the price.
content.inboundSmsCallbackUrl
The defined callback URL that will receive the inbound sms messages.
content.voiceInboundStrategy
Represents the voice inbound strategy.
content.voiceInboundStrategy.dialplanUrl
The defined dialplan URL.
content.inboundVoiceCallbackUrl
The defined callback URL that will receive the inbound voice messages.
content.nextRenewal
The date that the msisdn will automatically renew at.
Create a Pool
Creates a new pool
RESPONSE PARAMETERS
poolId
The tracking id of the pool.
poolName
The name of the pool.
smsSettings
The SMS settings of the pool.
smsSettings.sticky
When enabled, the service should try to always use the same number, as sender, for each recipient.
smsSettings.geomatch
When enabled, the service should try to use, as sender, a number that matches the destination country.
smsSettings.transcode
When enabled, the SMS message will get transcoded (when possible).
smsSettings.defaultCountry
A country code in ISO 3166-1 alpha-2 format. Routee will use a number from this defaultCountry as sender, if there is not a more suitable option (eg a number from the same country or a sticky sender for the recipient).
smsSettings.alphanumericSenderId
The alphanumeric Sender Id that will be used, when the pool strategy is "Alphanumeric".
smsSettings.inboundSMSCallbackUrl
Defines the callback URL that will receive the inbound messages to the numbers of the pool.
smsSettings.callback
Defines the callback URL that will receive the status update notifications for your outbound SMS messages.
smsSettings.callback.url
A URL that Routee will POST to, each time your message status changes.
smsSettings.callback.strategy
Defines when the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
updatedAt
The timestamp the pool is created.
Send SMS using a Pool
Sends a single SMS using a pool
RESPONSE PARAMETERS
trackingId
The tracking Id of the SMS message.
status
The status of the SMS. Check here for possible values.
createdAt
The date that this resource was created.
poolId
The trackingId of the pool.
poolName
The name of the pool.
poolStrategy
The followed strategy when picking a sender from the pool. Values: Numeric, Alphanumeric
smsSettings
The SMS settings of the pool
smsSettings.sticky
When enabled, the service should try to always use the same number, as sender, for each recipient.
smsSettings.geomatch
When enabled, the service should try to use, as sender, a number that matches the destination country.
smsSettings.transcode
When enabled, the SMS message will get transcoded (when possible).
smsSettings.defaultCountry
A country code in ISO 3166-1 alpha-2 format. Routee will use a number from this defaultCountry as sender, if there is not a more suitable option (eg a number from the same country or a sticky sender for the recipient).
smsSettings.alphanumericSenderId
The alphanumeric Sender Id that will be used, when the pool strategy is "Alphanumeric".
smsSettings.inboundSMSCallbackUrl
Defines the callback URL that will receive the inbound messages to the numbers of the pool.
smsSettings.callback
Defines the callback URL that will receive the status update notifications for your outbound SMS messages.
smsSettings.callback.url
A URL that Routee will POST to, each time your message status changes.
smsSettings.callback.strategy
Defines when the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
to
The recipient of the SMS. Format with a '+' and country code e.g., +3069485xxxxx (E.164 format).
from
The sender Id (number or alphanumeric) that picked from the pool (without the '+')
bodyAnalysis
The analysis for the body of the SMS.
bodyAnalysis.characters
The total number of characters of the message body.
bodyAnalysis.parts
The number of actual SMS that will be sent.
bodyAnalysis.transcode
Contains information for the transcoded body of the SMS message. This will be available only if the message can be transcoded.
bodyAnalysis.transcode.message
The transcoded message of the original unicode message.
bodyAnalysis.transcode.parts
The number of the parts of the transcoded message.
bodyAnalysis.unicode
Indicates if the body contains unicode characters.
bodyAnalysis.unsupportedGSMCharacters
Which characters caused the message to be considered as unicode.
Delete a Pool
Deletes an existing pool
RESPONSE PARAMETERS
poolId
The tracking id of the pool.
deletedAt
The timestamp the pool is deleted.
Edit a Pool
Edits an existing pool
RESPONSE PARAMETERS
poolId
The tracking id of the pool.
poolName
The name of the pool.
smsSettings
The SMS settings of the pool.
smsSettings.sticky
When enabled, the service should try to always use the same number, as sender, for each recipient.
smsSettings.geomatch
When enabled, the service should try to use, as sender, a number that matches the destination country.
smsSettings.transcode
When enabled, the SMS message will get transcoded (when possible).
smsSettings.defaultCountry
A country code in ISO 3166-1 alpha-2 format. Routee will use a number from this defaultCountry as sender, if there is not a more suitable option (eg a number from the same country or a sticky sender for the recipient).
smsSettings.alphanumericSenderId
The alphanumeric Sender Id that will be used, when the pool strategy is "Alphanumeric".
smsSettings.inboundSMSCallbackUrl
Defines the callback URL that will receive the inbound messages to the numbers of the pool.
smsSettings.callback
Defines the callback URL that will receive the status update notifications for your outbound SMS messages.
smsSettings.callback.url
A URL that Routee will POST to, each time your message status changes.
smsSettings.callback.strategy
Defines when the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
updatedAt
The timestamp the pool is updated.
Retrieve all the Pools of an account
RESPONSE PARAMETERS
poolId
The tracking id of the pool.
poolName
The name of the pool.
smsSettings
The SMS settings of the pool.
smsSettings.sticky
When enabled, the service should try to always use the same number, as sender, for each recipient.
smsSettings.geomatch
When enabled, the service should try to use, as sender, a number that matches the destination country.
smsSettings.transcode
When enabled, the SMS message will get transcoded (when possible).
smsSettings.defaultCountry
A country code in ISO 3166-1 alpha-2 format. Routee will use a number from this defaultCountry as sender, if there is not a more suitable option (eg a number from the same country or a sticky sender for the recipient).
totalNumbers
The total numbers of the pool
updatedAt
The timestamp the pool is updated.
Retrieve info for a specific Pool
RESPONSE PARAMETERS
poolId
The tracking id of the pool.
poolName
The name of the pool.
smsSettings
The SMS settings of the pool.
smsSettings.sticky
When enabled, the service should try to always use the same number, as sender, for each recipient.
smsSettings.geomatch
When enabled, the service should try to use, as sender, a number that matches the destination country.
smsSettings.transcode
When enabled, the SMS message will get transcoded (when possible).
smsSettings.defaultCountry
A country code in ISO 3166-1 alpha-2 format. Routee will use a number from this defaultCountry as sender, if there is not a more suitable option (eg a number from the same country or a sticky sender for the recipient).
smsSettings.callback.url
A URL that Routee will POST to, each time your message status changes.
smsSettings.callback.strategy
Defines when the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
updatedAt
The timestamp the pool is updated.
totalNumbers
The total numbers of the pool.
Retrieve the Numbers that belongs to a specific Pool
RESPONSE PARAMETERS
poolId
The tracking id of the pool.
poolName
The name of the pool.
numbers
The numbers of the pool
Perform a voice conversation
RESPONSE PARAMETERS
trackingId
The id of the conversation.
direction
The direction of the conversation (Inbound or Outbound).
from
The sender id of the conversation.
to
The recipient of the conversation.
to.phone
A valid phone number (mobile or landline).
to.sip
A valid SIP URI.
(ex 1111@test.com:55080)
dialPlanUrl
The url that contains a combination of action verbs to be executed.
dialPlans
A combination of action verbs to be executed.
dialPlans.verbs
The array of SAY, PLAY, DIAL and COLLECT verbs. Check here for possible values.
callback
Defines the notification callback information for the progress of Voice conversation.
callback.url
The URL that will be called when an update occurs.
callback.strategy
When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
hangupDelay
The time to wait for the call to be answered.
The default value is to wait for the network to terminate the call.
createdAt
The time the conversation was created.
maxDuration
The maximum duration.
machineDetection
It is used to detect if the call is answered by human or machine and define the desired actions (in case of machine).
machineDetection.strategy
The strategy to follow when a machine has been detected. Possible values: "Hangup" (terminate the call) or "Continue" (give another dialplan to execute).
machineDetection.eventUrl
The URL that Routee will POST to when a machine is detected (only for "Continue" strategy). A valid dialplan is expected as response.
Retrieve Conversation by TrackingId
Retrieve tracking information for conversation
RESPONSE PARAMETERS
trackingId
The id of the conversation.
direction
The direction of the conversation (inbound or outbound)
from
The sender Id of the conversation
to
The recipient of the conversation.
to.phone
A valid phone number (mobile or landline).
to.sip
A valid SIP URI.
dialPlanUrl
The url that contains a combination of action verbs to be executed.
callback
Defines the notification callback information for the progress of Voice conversation.
callback.url
The URL that will be called when an update occurs.
callback.strategy
When the URL will be called. Two possible values: on every status change (OnChange) or when a final status arrives (OnCompletion).
hangupDelay
The time to wait for the call to be answered.
maxDuration
The maximum duration.
createdAt
The time the conversation was created.
recordings
Information about the related recorded files.
recordings.trackingId
The tracking Id of the recorded file.
recordings.start
The start time of the recording (ISO-8601 date-time format).
recordings.end
The end time of the recording (ISO-8601 date-time format).
recordings.from
The initiator of the DIAL.
(the recipient of the conversation)
recordings.to
The recipient of the DIAL.
recordings.url
The url to download the recorded file.
recordings.voiceTrackingIds
An array with the tracking Ids of the voice messages related to the conversation.
recordings.conversationTrackingId
The tracking Id of the voice conversation.
recordings.duration
The duration of the recording (in seconds).
machineDetection
It is used to detect if the call is answered by human or machine and define the desired actions (in case of machine).
machineDetection.strategy
The strategy to follow when a machine has been detected. Possible values: "Hangup" (terminate the call) or "Continue" (give another dialplan to execute).
machineDetection.eventUrl
The URL that Routee will POST to when a machine is detected (only for "Continue" strategy). A valid dialplan is expected as response.
Retrieve Conversation dial Tracking
You can get all the tracking information for the voice trackings by providing the conversation tracking id