REST API

Marcelo Gornstein edited this page Feb 27, 2017 · 251 revisions

Contents

Introduction

Endpoints


Deprecated API


About

Welcome!

This is the API for PortaText. It envisions to serve different purposes:

  • Send SMS
  • Manage templates, campaigns, contacts, etc.
  • Reporting
  • etc

It also tries to be efficient in serving the needs of different actors:

  • 3rd party software that wants to send SMS: These will most likely use an API Key as a way to interact with the system.
  • Web or Mobile clients that offer more capabilities (like reporting, account configuration, etc): These will need different capabilities (session handling and expiration, user login, etc).

Hopefully the chosen REST interface will be good enough to serve all these needs but also be self-descriptive and discoverable, allowing you (the application developer) to write all kind of applications without worrying about the gory details, and just focus on writing a cool UI.

Please take a moment to read through this documentation and have a clear view of what is offered by the API and its different entry points and authentication methods.

Enjoy!


Available SDKs

We have several open source clients available for different languages in our GitHub account at https://github.com/PortaText. You can also checkout our wiki for Available SDKs for more information.


Endpoints

The main endpoint for the PortaText API is https://rest.portatext.com.


Authentication and Authorization

There are no public entry points. All API calls must be authenticated and authorized. Different API calls will accept one or more ways to do it, and this is due to the nature of what they are used for. Typically one would use HTTP Basic Auth to login and get a session token, and then use the Session Authentication to issue calls. Or perhaps an integration in a 3rd party software would be better off with using an API Key Authentication.

API Key

All calls must contain a header X-Api-Key used for Authentication, Authorization, and Accounting.

Trying it with curl: Use the -H switch, like:

$ curl -vXGET https://rest.portatext.com/entry_point -H'X-Api-Key: MyKey'

NOTE: This authentication method is restricted to an ACL based on ip addresses (the others are not). See the /acl entry point.

HTTP Basic

HTTP Basic Autentication is a standard way of authentication for the web. All major libraries support it natively. It consists in sending the header Authorization with a base64 string formed from a username and password, like username:password:

Trying it with curl: Use the -u switch, like:

$ curl -vXGET https://rest.portatext.com/entry_point -uname:password

Session Authentication

All calls must contain a header X-Session-Token used for Authentication, Authorization, and Accounting.

Trying it with curl: Use the -H switch, like:

$ curl -vXGET https://rest.portatext.com/entry_point -H'X-Session-Token: MyToken'

The only way to get a session token is to use HTTP Basic auth against the /login entry point. Remember that session tokens expire on inactivity, so if you get a 401 when using this authentication method try hitting the /login entry point to get a new token.

HTTP WebBasic

When creating a webapp to interface with the PortaText REST API, you will need to authenticate the user and hit the different endpoints. When auth Basic is used, the browser will automatically display an authorization popup dialog asking the user for his/her credentials. This is annoying and usually and undesired effect.

To overcome this issue, make sure your webapp adds the header X-Web-Request to the request and send the type WebBasic in the authorization header, which is just the same as Basic but will not let the browser display the dialog (it wont recongnice it as a supported authentication method).

Example:

$ curl -kvXPOST https://rest.portatext.com/login -H'X-Web-Request: true' -H'Authorization: WebBasic dXNlcjpwYXNzd29yZA=='


Common Standards

The API behaves as follows:

  • Every request (including GETs) should be authenticated and authorized by one of the authentication methods.
  • Every request should contain the headers:
  • Content-Type: application/json (Some endpoints will require text/csv to upload files)
  • Accept: application/json (some endpoints will require text/csv as they export data in that format)
  • Every response will contain the headers:
  • X-PortaText-Request-Time: How many milliseconds took your request for being processed.
  • The following status codes are used by all the API:
  • 200: Success.
  • 201: When a new resource is created (A Location header will be returned with the path to the new resource).
  • 202: The operation was accepted and will be processed at a later unspecified time. Usually you will be notified of the final result through the Notifications.
  • 400: Invalid parameters.
  • 401: Invalid authentication credentials.
  • 402: If credits or funds are not enough for the requested operation.
  • 403: Authentication was successful, but access is denied for the given resource (i.e: client is disabled).
  • 404: Resource not found.
  • 405: Method not Allowed (e.g: Doing a POST against an endpoint that does not support it).
  • 406: Not Acceptable. You probably sent the wrong Accept header.
  • 415: Wrong media type sent (in Content-Type and/or Accept headers).
  • 429: Rate limited. You are making too many requests too fast. Check the header X-Rate-Limit-Reset to know when the limit will be reset. Until then, don't make any more requests or you will be penalized for every extra request.
  • 500: On server error (i.e: not your fault!)
  • HTTP verbs are used extensively. An endpoint will usually accept more than 1 verb:
  • Use POST to create a resource
  • Use PUT to update a resource
  • Use PATCH to partially update a resource (not all endpoints will support this)
  • Use DELETE to delete a resource
  • Use GET to get one or more resources
  • Use OPTIONS to find out supported methods on a endpoint
  • Will always accept and send back a JSON payload.
  • Some actions might not return any content at all.
  • All JSON responses will return a property named success that will be either true or false. When success is false, an extra field is returned error_description with an array of strings indicating errors.


Common errors

These errors should be expected while interacting with any of the endpoints.

  • missing_id: The endpoint expected to receive an entity id in the path.
  • not_found: The resource was not found.
  • internal_server_error: Something unexpected happen and probably is not your fault.
  • invalid_json_payload: The payload was not a well formed json string.


Did types

Whenever you encounter a did type (asked for, or returned from, an API endpoint), it can be one of the following:

  • local
  • national
  • mobile
  • toll_free


User Settings

Some behaviors of the system will depend or rely on different user settings. These are controlled via the Settings API that will allow you to set and unset them. When a setting is not present, a default action is taken or the feature is ignored completely. This is a list of the supported types:

  • alert_when_credit_less_than: Integer. When present, the system will issue 1 alert per day at most when the client credit is less than the specified value.
  • email_on_inbound_sms: String. When present, the system will send an email for every inbound SMS received.
  • autorecharge_enabled: Boolean. Enable autorecharges.
  • default_card_id: Integer. Credit card id. See the Credit Cards API
  • autorecharge_when_credit: Integer. Autorecharge account when the credit balance reaches this number.
  • autorecharge_total: Integer. Autorecharge this amount of money credits with the credit_cost assigned to the client when the credit balance reaches autorecharge_when_credit, only if autorecharge_enabled is true.
  • amd_max_word_length: Integer. Used for telephone campaigns only. Is the maximum duration of a word to accept (milliseconds).
  • amd_silence_threshold: Integer. Used for telephone campaigns only. How long do we consider silence (milliseconds).
  • amd_max_words: Integer. Used for telephone campaigns only. Is the maximum number of words in a greeting.
  • amd_between_words_silence: Integer. Used for telephone campaigns only. Is the minimum duration of silence after a word to consider the audio that follows to be a new word (milliseconds).
  • amd_min_word_length: Integer. Used for telephone campaigns only. Is the minimum duration of Voice considered to be a word (milliseconds).
  • amd_total_time: Integer. Used for telephone campaigns only. Is the maximum time allowed for the algorithm (milliseconds).
  • amd_after_greeting_silence: Integer. Used for telephone campaigns only. Is the silence after detecting a greeting (milliseconds).
  • amd_max_greeting_length: Integer. Used for telephone campaigns only. Is the maximum length of a greeting (milliseconds).
  • amd_initial_silence: Integer. Used for telephone campaigns only. Is maximum initial silence duration before greeting (milliseconds).
  • sns_publish_enabled: Boolean. Enable publishing of events to a SNS Topic. The events published can be found in Notifications.
  • sns_access_key: String. Amazon AWS access key needed to publish to the SNS Topic.
  • sns_access_secret: String. Amazon AWS access secret needed to publish to the SNS Topic.
  • sns_topic: String. SNS topic ARN for publishing.


DID Settings

A DID has some settings that users can set at will. These are controlled via the DID Settings API that will allow you to set and unset them. This is a list of the supported types:

  • cnam_enabled: Boolean. Turns on/off the automatic CNAM lookup on every SMS inbound. These are charged in credits, with the amount that the cnam_credit_cost field of the did specified.
  • clookup_enabled: Boolean. Turns on/off the automatic full client lookup on every SMS inbound. These are charged in credits, with the amount that the clookup_credit_cost field of the did specified.
  • autoresponder_enabled: Boolean. Turns on/off an automatic autoresponder that will be sent with every inbound SMS.
  • autoresponder_text: String. Sets the text to be sent with the automatic response.
  • stop_words_enabled: Boolean. When enabled (true) it will autodetect the word "STOP" in inbound SMS' and will automatically blacklist the sender. This is an extreme case that allows your users to avoid receiving any further communications from you.


Jobs

Some operations will return a job id. Jobs are background operations that finish some time after they are requested. Jobs can be queried and acted upon by using the Jobs API. You can also be notified when a job ends by setting up Notifications.

To know more about jobs, you can read our blog post "Asynchronicity: How do we love thee? Let us count the ways!".

Jobs can have one these types:

  • contact_list_import
  • campaign_create
  • number_inspect
  • contacts_import

Jobs will finish in one of these states:

  • finished
  • failed
  • cancelled

Jobs with files as result

Some jobs (like the type "number_inspect", started by the Number Inspect API) will have files as a result that you can download. These files will usually have a maximum lifetime of 24 hours, so you should download them as soon as possible in order to save this information.

To download the resulting file of a job, use the Job Result API.



Blacklist

Every client has one blacklist where contacts can be added/deleted/imported through the Blacklist API and the Blacklist Contacts API.

When a number is added to this list, messages will never be sent to the number.



Campaigns

Campaigns allow you to massively send messages to a set of Contact Lists (blacklisted contacts will be silently discarded). You can also send a CSV file with the list of contacts instead of a list of contact list IDs. You can manage campaigns through the Campaigns API.

Campaigns have a lifecycle and the user can interact with it through the Campaigns Lifecycle API. The possible states of a campaign lifecycle can be one of:

  • Ready
  • Running
  • Paused
  • Cancelled
  • Finished

Campaigns also allow to have Schedules for calls and messages.

Types

Currently, you can create these different types of campaigns:

  • SMS
  • Telephony

Each campaign type will have its own different, specialized, settings (and restrictions) to set them up.

Settings

SMS

  • template_id: See same variable in /sms.
  • text: See same variable in /sms.
  • variables: See same variable in /sms.

Telephony

  • iterations: Required. Integer. Total attempts for a given contact. Must be > 0 and <= 5.
  • agents: Required. Integer. Number of agents taking calls for this campaign. Must be > 0 and <= 100. The system will automatically limit this if your total number of telephone agents allowed is lower than the number specified here.
  • post_call_work_duration: Required. Integer. Specifies (in seconds) the total time that an agent needs as a wrap-up time or closure time after each call. Must be > 0 and <= 600.
  • min_iteration_time: Required. Integer. Specifies (in minutes) the minimum time that the system must wait before attempting to contact a number in the next iteration.
  • dial_timeout: Required Integer. Specifies (in seconds) the maximum time to wait for an answer on Leg A when trying to reach a contact.
  • outbound_trunk_id: Required. Integer. The trunk ID used to make the calls (Leg A).
  • flow: Required when creating a telephony campaign. A list (array) of Telephony Call Flow Objects.

Useful considerations

  • For every message sent you will receive the standard notifications (status, delivery_status, etc). See Notifications.
  • Every campaign starts in the ready state.
  • Every campaign will reach one of terminal states finished (when they complete normally -i.e: all messages have been sent or tried to be sent-) or cancelled when the user intentionally cancels the campaign.
  • Once a campaign reaches a terminal state, it can't be restarted or resumed.
  • Only campaigns in the running state are actually sending messages. Campaigns in other states will not send any messages.

Telephony Call Flow Objects

When creating telephony campaigns one should specify the call flow by using Flow Objects, and these will also affect the final outcome for every call (see our FAQ entry "How do you determine that a given target has been contacted?"). The available flow objects are:

Wait

Waits a specified amounts of seconds.

{
  "wait": {
    "seconds": 5
  }
}

Play

Plays the given sound id, created with the Sounds API.

{
  "play": {
    "sound_id": 3
  }
}

Forward

Forward the call through the specified trunk id, created with the Trunks API. The timeout parameter is maximum time (in seconds) allowed for the call (Leg B) to be answered once dialed through the given trunk id.

{
  "forward": {
    "trunk_id": 4,
    "timeout": 30
  }
}

AMD

Starts Answering Machine Detection (AMD) when the contact answers the call and executes the given call flow objects depending on the result (either if a human or machine was detected, or if the algorithm couldn't detect it for sure).

Note that the AMD object can't be nested (you can only run AMD just once in your whole call flow).

AMD Settings can be configured in the User Settings.

{
  "amd": {
    "if_human": [...],
    "if_machine": [...],
    "if_notsure": [...]
  }
}

Lifecycle workflow

When a campaign is:

  • ready: The user can cancel it (moving it to the cancelled state) or start it (moving it to the running state).
  • running: The user can cancel it or pause it (moving it to the paused state).
  • paused: The user can cancel it or resume it (moving it back again to the running state).


SMS Services

SMS Services are further described in our FAQ. An SMS Service is composed by a short code and a keyword. Short codes are:

  • 4 to 6 digits long.
  • Only useful to reach destinations in the same country as the short code.
  • Useful to send marketing messages in high volume.

The keyword is 4 to 16 characters long and identifies your service in that short code so your users/clients can interact with it. For example, you can have a service running in the short code 12345 inside the US, and accessible via the short code PORTATEXT.

Users can subscribe to and unsubscribe from your service with a simple SMS.

SMS Services can't be created by you, but you can apply for one. Also, you can interact with your SMS Services via the SMS Services API and with the SMS Services Subscribers API.



Schedules

You can use different schedules to send messages (either for campaigns or single messages -including group messaging and such-) at specific hours or days. These days and hours will be relative to the time zone of each one of the destinations.

For example, when scheduling that a message will be sent (or that a campaign will send its messages) "from 9 to 17" this means that each one of the destinations will be evaluated separately to know its own time zone, and the message will be sent from 9 to 17 in each one of those specific time zones. If one of those destinations is already past the hours allowed, the message(s) will be sent on the next day for that time zone.

For more information you can read our FAQ Entry "Can I schedule my messages so specific times are honored for the targets?" and our blog post Schedule your SMS Marketing Campaigns for a better ROI.

Types

This a list of all the available schedule types:

  • any_day: Accepts arguments from and to, both in 24 hour-format and 2-digit padded. Use this schedule when a message can be sent in any day of the week (from Monday to Sunday) but only at the specified hours. Example:
"any_day": {
  "from": "09:15",
  "to": "14:26"
}
  • specific_days: Same as any_day, but it also accepts an extra argument days with the week days where the schedule applies. Messages and calls will only be sent/issued on the allowed days and only during the given from-to hours. Example:
"specific_days": {
  "days": ["Sat", "Sun"],
  "from": "09:15",
  "to": "14:26"
}

Dates are the first 3 letters of any of the given days of the week. Valid values are:

  • Mon
  • Tue
  • Wed
  • Thu
  • Fri
  • Sat
  • Sun

Common errors

The following is a list of common errors that your code should expect for any endpoint that accepts a schedule as one of its arguments:

  • schedule_invalid
  • schedule_from_required
  • schedule_to_required
  • schedule_from_invalid
  • schedule_to_invalid
  • schedule_not_supported
  • schedule_object_invalid
  • days_required
  • days_invalid


Endpoints

/login

Description

Log in a user with email and password. This will return a session token to be used with the Session Authentication method.

Authentication methods

  • Basic

Methods

  • POST

Returns

  • 200: On success.

POST Example

$ curl -kvXPOST https://rest.portatext.com/login \
  -ud3@toyota.com:4d84a15f \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

PHP

The php-sdk will automatically login when needed if you specify your credentials.

$client->setCredentials($username, $password);

Ruby

The ruby-sdk will automatically login when needed if you specify your credentials.

client.credentials = [username, password]

NodeJS

The node-sdk will automatically login when needed if you specify your credentials.

client.setCredentials(username, password);

/me

Description

Allows to get and set personal information. Used to change things like company, email, first_name, and last_name. DIDs are also returned.

Authentication methods

  • Session
  • API Key

Arguments

  • first_name: Required. String.
  • last_name: Required. String.
  • company: Required. String.
  • email: Required. String.
  • callback_url: Optional. String. Please also see: Notifications. You will have to handle the test payload when setting this argument.
  • timezone: Required. String. See the Timezones API.
  • language: String. One of "en", "es". Your preferred language.

Methods

  • PUT
  • GET

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • invalid_email
  • email_already_exists
  • first_name_required
  • first_name_too_short
  • first_name_too_long
  • last_name_required
  • last_name_too_short
  • last_name_too_long
  • company_required
  • company_too_short
  • company_too_long
  • email_required
  • invalid_url
  • url_not_responding
  • timezone_required
  • invalid_timezone
  • language_required
  • language_invalid

PHP Examples

Check out the me tests.

Ruby Examples

Check out the me tests.

NodeJS Examples

Check out the me tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/me \
  -H'X-Api-Key: your_token'

PUT Example

$ curl -kvXPUT https://rest.portatext.com/me \
  -H'X-Api-Key: your_token' \
  -d'{"first_name": "new_first_name", "last_name": "new_last_name", "company": "company, llc", "email": "new_email@host.com", "callback_url":"https://mycompany.com/callback", "timezone": "Etc/UTC"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/me/password/reset/:nonce

Description

Asks to and resets a password.

Authentication methods

  • None

Arguments

  • nonce: String. Required only when resetting the password. Passed in path.
  • email: String. Required only when asking for a nonce.
  • new_password: Required. String. New password to set. Password must:
  • Have more than 8 characters.
  • Have at least 1 digit.
  • Have at least 1 lowercase letter.
  • Have at least 1 uppercase letter.
  • Have at least 1 non alphanumeric character ($, !, #, etc).

Methods

  • PUT (Resets a password with a nonce).
  • POST (Requests a link with a nonce used to reset a password).

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • new_password_required
  • invalid_nonce
  • invalid_email
  • weak_password

PHP Examples

Check out the my_password tests.

Ruby Examples

Check out the my_password tests.

NodeJS Examples

Check out the my_password tests.

POST Example

$ curl -kvXPUT https://rest.portatext.com/me/password/reset\
  -H'X-Session-Token: your_session_token' \
  -d'{"email": "user@host.com"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

PUT Example

$ curl -kvXPUT https://rest.portatext.com/me/password/reset/SOMENONCE \
  -H'X-Session-Token: your_session_token' \
  -d'{"new_password": "someGREATpassword838$!"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/me/password

Description

Changes password.

Authentication methods

  • Session

Arguments

  • old_password: Required. String. Current password.
  • new_password: Required. String. New password to set. Password must:
  • Have more than 8 characters.
  • Have at least 1 digit.
  • Have at least 1 lowercase letter.
  • Have at least 1 uppercase letter.
  • Have at least 1 non alphanumeric character ($, !, #, etc).

Methods

  • PUT

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • old_password_required
  • new_password_required
  • wrong_password
  • weak_password

PHP Examples

Check out the my_password tests.

Ruby Examples

Check out the my_password tests.

NodeJS Examples

Check out the my_password tests.

PUT Example

$ curl -kvXPUT https://rest.portatext.com/me/password \
  -H'X-Session-Token: your_session_token' \
  -d'{"old_password": "my_old_password", "new_password": "someGREATpassword838$!"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/acl

Description

Configures the ACL.

Authentication methods

  • Session

Arguments

  • acl: Required. List of ACL objects. Each object has the following keys:
  • ip: Required. String.
  • netmask: Required. Integer.
  • description: Required. String

Methods

  • PUT (Overwrites ACL)
  • GET (Gets the ACL)

Returns

  • 200: On success.

Errors (These are PER acl entry)

  • description_required
  • invalid_netmask
  • invalid_address

PHP Examples

Check out the acl tests.

Ruby Examples

Check out the acl tests.

NodeJS Examples

Check out the acl tests.

PUT Example

$ curl -kvXPUT https://rest.portatext.com/acl \
  -H'X-Session-Token: your_session_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"acl": [{"ip": "192.168.0.1", "netmask": 32, "description": "my pc"}, {"ip": "54.54.22.0", "netmask": 16, "description": "office"}]}'

The result on error should be a status 400 and the acl list is returned in order, with an additional field named errors describing what went wrong with each one of the acl addresses.

GET Example

$ curl -kvXGET https://rest.portatext.com/acl \
  -H'X-Session-Token: your_session_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/me/settings

Description

Configures user settings. See User settings:

  • This endpoint allows you to set/get one or more settings.
  • Errors when setting values (if any) will be returned with a json object where the key is the setting and the value is an array of one or more errors.
  • When setting multiple settings there must be no errors in order to commit all changes, otherwise no changes will be done.
  • To unset a setting, set it to null.

Authentication methods

  • Session
  • API Key

Arguments

Methods

  • PATCH (Overwrites one or more settings)
  • GET (Gets all settings)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors.

  • value_cant_be_below_0
  • value_cant_be_below_1
  • invalid_email
  • unknown_setting
  • integer_required
  • string_required
  • boolean_required

PHP Examples

Check out the settings tests.

Ruby Examples

Check out the settings tests.

NodeJS Examples

Check out the settings tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/me/settings \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

PATCH Example

$ curl -kvXPATCH https://rest.portatext.com/me/settings \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"alert_when_credit_less_than": null, "email_on_inbound_sms": "other_email@mail.com"}'

/dids/:did

Description

Get or Set DID settings. See DID settings:

  • This endpoint allows you to set one or more settings.
  • Errors when setting values (if any) will be returned with a json object where the key is the setting and the value is an array of one or more errors.
  • When setting multiple settings there must be no errors in order to commit all changes, otherwise no changes will be done.

If you want to get all the DIDs assigned to you, use the /me endpoint.

Authentication methods

  • Session
  • API Key

Arguments

Methods

  • PATCH (Overwrites one or more settings)
  • GET (Get DID settings)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors.

  • unknown_setting
  • boolean_required
  • string_required
  • message_too_short

PHP Examples

Check out the did settings tests.

Ruby Examples

Check out the did settings tests.

NodeJS Examples

Check out the did settings tests.

PATCH Example

$ curl -kvXPATCH https://rest.portatext.com/dids/12036527091 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"cnam_enabled": true}'

GET Example (For a specific DID)

$ curl -kvXGET https://rest.portatext.com/dids/12036527091 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (For all DIDs)

$ curl -kvXGET https://rest.portatext.com/dids\
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/credit_cards/:id

Description

Manages credit cards.

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required only on DELETE. String. Passed in path.
  • first_name: Required. String.
  • last_name: Required. String.
  • address: Required. String.
  • city: Required. String.
  • state: Required. String.
  • zip: Required. String.
  • country: Required. String.
  • card_number: Required. String.
  • card_expiration_date: Required. String. In the form: YYYY-MM.
  • card_code: Required. String. 3 or 4 chars length.

Methods

  • GET (Returns all known credit cards).
  • POST (Creates a credit card).
  • DELETE (Deletes a credit card).

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors.

  • first_name_required
  • last_name_required
  • address_required
  • city_required
  • state_required
  • zip_required
  • country_required
  • card_number_required
  • card_expiration_date_required
  • card_expiration_date_invalid
  • card_code_required
  • card_code_too_short
  • card_code_too_long
  • card_is_in_use
  • You should also expect different errors here, like AVS/CVV failed checks, etc.

PHP Examples

Check out the credit card tests.

Ruby Examples

Check out the credit card tests.

NodeJS Examples

Check out the credit card tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/credit_cards \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"first_name": "first", "last_name": "last", "address": "address", "city": "city", "state": "state", "zip": "zip", "country": "country", "card_number": "6011000000000012", "card_expiration_date": "2015-08", "card_code": "900"}'

GET Example

$ curl -kvXGET https://rest.portatext.com/credit_cards \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/credit_cards/32542755 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/me/email_verify

Description

Requests to/or confirms an email.

Authentication methods

  • Session
  • None (When verifying the email with the nonce id).

Arguments

  • nonce: Required when validating an email. String. Passed in path.

Methods

  • POST (Requests a link to confirm the email).
  • PUT (Confirms an email with a nonce).

Returns

  • 202: On success.
  • 400: On invalid parameters (check the field error_description for details).

PHP Examples

Check out the email verify tests.

Ruby Examples

Check out the email verify tests.

NodeJS Examples

Check out the email verify tests.

POST Example (Requesting email confirmation)

$ curl -kvXPOST https://rest.portatext.com/me/email_verify \
  -H'X-Session-Token: CF107A64D27B80AC8F910197570BCF636DC876BA96C28E2B69DFE6CAB123312D' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

PUT Example (When verifying an email with a nonce id, and no authorization is required)

$ curl -kvXPOST https://rest.portatext.com/me/email_verify/B3346049BACE37E808F3B5284AC6270950B4C71C9103445652AC90720E0A7FE5 \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/templates

Description

Manages templates. Templates use the mustache template engine. To know more, you can read Using Templates to Send Personalized Messages.

Authentication methods

  • Session
  • API Key

Arguments

  • name: Required. String.
  • description: Required. String.
  • text: Required. String.

Methods

  • PUT (Updates a template)
  • POST (Creates a template)
  • GET (Gets a template -or all templates- information)
  • DELETE (Deletes a template)

Returns

  • 200: On success.
  • 201: On new template creation.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid ID.

Errors

  • name_already_exists
  • name_required
  • name_too_short
  • name_too_long
  • description_required
  • description_too_short
  • text_required
  • text_too_short

PHP Examples

Check out the templates tests.

Ruby Examples

Check out the templates tests.

NodeJS Examples

Check out the templates tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/templates \
  -H'X-Api-Key: your_token' \
  -d'{"name": "template_name", "description": "just a a template test", "text": "hello {{name}} how are you?"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (for one template)

$ curl -kvXGET https://rest.portatext.com/templates/2 \
  -H'X-Api-Key: your_token'

GET Example (for all templates)

$ curl -kvXGET https://rest.portatext.com/templates \
  -H'X-Api-Key: your_token'

PUT Example

$ curl -kvXPUT https://rest.portatext.com/templates/2 \
  -H'X-Api-Key: your_token' \
  -d'{"name": "template_name", "description": "just a a template test", "text": "hello {{name}} how are you?"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/templates/2 \
  -H'X-Api-Key: your_token'

/sms

Description

Sends SMS, and search for SMS operations. Check out "How are my messages billed?" for more information on how you will be charged per message sent.

NOTE: You can also simulate the sending of your message before actually sending it.

Authentication methods

  • Session
  • API Key

Arguments (for POST, sent on body)

  • to: Required. String. In E164 format (i.e: US numbers with the leading "1", etc).
  • from: Required unless service_id is used. String. DID to use. In E164 format (i.e: US numbers with the leading "1", etc). You can also send an array of DIDs and one will be selected at random from those. If you send the keyword "any", a random DID will be selected from the ones available in your account.
  • service_id: Required unless from is used. Integer. SMS Service ID to use.
  • template_id: Required (unless text is used). Integer. Template ID number to use.
  • text: Required (unless template_id is used). String. Text to send.
  • variables: Required. Object. Variables to replace in template.
  • client_ref: Optional. String. Useful to track messages related to a specific application behavior.
  • whatsapp: Optional. Boolean. Set to true to send via WhatsApp. Requires a WhatsApp-capable number.
  • contact_list_ids: Optional. Array of Integers. Use to send the message to a group of contact lists. Don't specify a to or service_id when using this.
  • schedule: Optional. Object. A Schedule object. If you send one, be ready to handle any of the possible schedule errors.

Arguments (for GET, sent on query string)

  • page: Optional. Integer. Page number for results.
  • from: Optional. String. Source telephone number in E164 (no leading '+').
  • to: Optional. String. Target telephone number in E164 (no leading '+').
  • date_from: Optional. String in format (yyyy-mm-ddTHH:MM:SS) Time zone is assumed to be the one for the account.
  • date_to: Optional. String in format (yyyy-mm-ddTHH:MM:SS) Time zone is assumed to be the one for the account.
  • status: Optional. String. One of: pending, sent, received, delivering, failed.
  • delivery_status: Optional. String. One of: delivered, unknown, undelivered, read.
  • type: Optional. String. One of: normal, opt_in, opt_out, number_verify, help, welcome, autoresponder.
  • direction: Optional. String. One of: inbound, outbound.
  • sort_order: Optional. String. One of: asc, desc.
  • sort_field: Optional. String. Currently the only value supported is date.
  • service_id: Optional. Integer. The ID of one of your SMS Services.
  • template_id: Optional. Integer. The ID of one of your Templates. ** campaign_id: Optional. Integer. The ID of one of your Campaigns.

Methods

  • POST (Sends an SMS)
  • GET (Retrieves the status of a previously initiated operation by passing :id or searches for SMS operations)

Returns

  • 202: On success (POST).
  • 200: On success (GET).
  • 400: On invalid parameters (check the field error_description for details).
  • 402: On insufficient credits for the requested operation.
  • 404: On invalid ID.

Errors (POST)

  • unknown_template
  • to_required
  • template_id_or_text_required
  • invalid_recipient
  • invalid_from
  • insufficient_credit
  • message_too_short
  • cant_send_to_destination
  • whatsapp_not_available
  • cant_use_template_id_and_text
  • blacklisted
  • unknown_contact_list_ids
  • unknown_service
  • service_disabled
  • cant_use_from_and_service_id
  • service_id_or_from_required
  • client_disabled
  • not_opted_in
  • If you use a schedule expect any of the possible schedule errors.

Errors (GET)

  • date_from_bigger_than_to
  • template_id_invalid
  • service_id_invalid
  • campaign_id_invalid
  • status_invalid
  • delivery_status_invalid
  • type_invalid
  • sort_order_invalid
  • sort_field_invalid
  • direction_invalid
  • date_from_invalid
  • date_to_invalid

NOTE: When sending to a group of contact lists, the result will be a detailed json object for each number of each contact list with the result, for example:

{
  "result": [
    {
      "contact_list_id": 2,
      "result": {
        "15045556666": {
          "operation_id": "1601e015065b-961c-496f-8681-3c8be9dc4e56",
          "success": true
        },
        "15046667777": {
          "operation_id": "1601632c604e-5f4c-407e-8b1f-165972398d7f",
          "success": true
        },
        "15048889999": {
          "operation_id": "1601bdeba381-4acb-49dd-9fcf-7294f343c874",
          "success": true
        },
        "1509990000": {
          "operation_id": "1601cd4d8edd-c9ea-4fc4-b930-e24bcf19cd89",
          "success": true
        }
      }
    },
    {
      "contact_list_id": 1,
      "result": {
        "15041111111": {
          "error_description": [
            "blacklisted"
          ],
          "success": false
        },
        "15043333333": {
          "operation_id": "160151737ac2-3064-4773-90de-400af1c2cb03",
          "success": true
        },
        "15044444444": {
          "operation_id": "16019e8e3528-83f2-407d-b554-a33000260b83",
          "success": true
        },
        "18882222222": {
          "error_description": [
            "cant_send_to_destination"
          ],
          "success": false
        }
      }
    }
  ],
  "success": true
}

PHP Examples

Check out the sms tests.

Ruby Examples

Check out the sms tests.

NodeJS Examples

Check out the sms tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/sms \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"to": "7869304016", "template_id": 3, "variables": {"name": "joe"}, "client_ref": "marketing_campaign_1"}'

GET Example

$ curl -kvXGET https://rest.portatext.com/sms/15051814ef67-c19b-4c9e-9cf8-6b21c76c624d \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (Search operation).

$ curl -kvXGET https://rest.portatext.com/sms?page=10&status=inbound&from=12223334444&date_from=2015-01-01T00:00:00 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/timezones

Description

Manages Time zones.

Authentication methods

  • Session
  • API Key

Arguments

None.

Methods

  • GET (Gets all time zones).

Returns

  • 200: On success.

PHP Examples

Check out the timezones tests.

Ruby Examples

Check out the timezones tests.

NodeJS Examples

Check out the timezones tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/timezones \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/tariffs/:id

Description

Lists tariff(s).

Authentication methods

  • Session
  • API Key

Arguments

Methods

  • GET (Gets a tariff -or all tariffs- information).

Returns

  • 200: On success.

PHP Examples

Check out the tariffs tests.

Ruby Examples

Check out the tariffs tests.

NodeJS Examples

Check out the tariffs tests.

GET Example (for one tariff)

$ curl -kvXGET https://rest.portatext.com/tariffs/us \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (for all tariffs)

$ curl -kvXGET https://rest.portatext.com/tariffs \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/cnam/:number

Description

CNAM lookup. For more information please see our FAQ entry titled "What is the CNAM Database?"

This can also be used to query multiple numbers at once by uploading a CSV and starting a Job. The result will be available via the Job Result API.

NOTES:

  • When querying multiple numbers: Use Content-Type: text/csv and Accept: application/json.
  • When querying a single number: Use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • number: Required unless uploading a CSV. Integer. Passed in path. The target number.

Methods

  • POST

Returns

  • 200: On success.
  • 202: On success when uploading a CSV to start a Job for multiple numbers.
  • 400: On invalid parameters (check the field error_description for details).
  • 402: When not enough funds.

Errors

  • not_supported
  • insufficient_credit
  • number_invalid

PHP Examples

Check out the cnam tests.

Ruby Examples

Check out the cnam tests.

NodeJS Examples

Check out the cnam tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/cnam/14082571500 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

POST Example (Multiple numbers)

$ curl -vXPOST 'https://rest.portatext.com/cnam \
  -H'X-Api-Key: your_token' \
  -H'Accept: application/json'
  -H'Content-Type: text/csv'

/recharge

Description

Recharges the account with a credit card.

Authentication methods

  • Session
  • API Key

Arguments

  • card_id: Required. Integer. To create a credit card see the credit card API.
  • total: Required. Float Integer. Total money credits to recharge.

Methods

  • POST (Recharges a prepaid account).

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • credit_card_required
  • recharge_too_low
  • not_prepaid
  • Be prepared to handle any kind of error strings if the transaction fails.

PHP Examples

Check out the recharge tests.

Ruby Examples

Check out the recharge tests.

NodeJS Examples

Check out the recharge tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/recharge \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' -d'{"card_id": 32544374, "total": 120}'

/jobs/:id

Description

Manages Jobs.

Authentication methods

  • Session
  • API Key

Arguments

  • id: Optional. Integer. Job ID. Passed in path.
  • page: Optional. Integer. Page number, passed in query string on GET.

Methods

  • GET (Gets a job -or all jobs- information)
  • DELETE (Cancels a job)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid ID.

Errors

  • not_active

PHP Examples

Check out the jobs tests.

Ruby Examples

Check out the jobs tests.

NodeJS Examples

Check out the jobs tests.

GET Example (for one job)

$ curl -kvXGET https://rest.portatext.com/jobs/1 \
  -H'X-Api-Key: your_token'

GET Example (for all jobs)

$ curl -kvXGET https://rest.portatext.com/jobs \
  -H'X-Api-Key: your_token'

DELETE Example (Cancels a job)

$ curl -kvXDELETE https://rest.portatext.com/jobs/1 \
  -H'X-Api-Key: your_token'

/jobs/:id/result

Description

Downloads the resulting file of a job execution.

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required. Integer. Job ID.

Methods

  • GET (Gets a job result)

Returns

  • 200: On success.
  • 404: On invalid ID or file not available.

Errors

PHP Examples

Check out the jobs tests.

Ruby Examples

Check out the jobs tests.

NodeJS Examples

Check out the jobs tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/jobs/1/result \
  -H'X-Api-Key: your_token' -H'Accept: */*'

/contact_lists

Description

Manages contact lists.

Authentication methods

  • Session
  • API Key

Arguments

  • name: Required. String.
  • description: Required. String.

Methods

  • PUT (Updates a contact list)
  • POST (Creates a contact list)
  • GET (Gets a contact list -or all contact lists- information)
  • DELETE (Deletes a contact list)

Returns

  • 200: On success.
  • 201: On new contact list creation.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid ID.

Errors

  • name_already_exists
  • name_required
  • name_too_short
  • name_too_long
  • description_required
  • description_too_short

PHP Examples

Check out the contact lists tests.

Ruby Examples

Check out the contact lists tests.

NodeJS Examples

Check out the contact lists tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/contact_lists \
  -H'X-Api-Key: your_token' \
  -d'{"name": "contact_list_name", "description": "just a a contact list test"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (for one contact list)

$ curl -kvXGET https://rest.portatext.com/contact_lists/2 \
  -H'X-Api-Key: your_token'

GET Example (for all contact lists)

$ curl -kvXGET https://rest.portatext.com/contact_lists \
  -H'X-Api-Key: your_token'

PUT Example

$ curl -kvXPUT https://rest.portatext.com/contact_lists/2 \
  -H'X-Api-Key: your_token' \
  -d'{"description":"just a a contact list test","id":2,"name":"contact_list_name"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/contact_lists/2 \
  -H'X-Api-Key: your_token'

/contact_lists/:contact_list_id/contacts/:contact

Description

Adds and removes contacts from the given contact list.

Authentication methods

  • Session
  • API Key

Arguments

  • contact_list_id: Required. Integer. Passed in path.
  • contact: Required. Integer. Passed in path.

Methods

  • PUT (Adds a contact to a contact list)
  • DELETE (Deletes the given contacts from the given contact list)

Returns

  • 200: On success when exporting.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid ID.

Errors

  • missing_id
  • missing_contact

PHP Examples

Check out the contact lists tests.

Ruby Examples

Check out the contact lists tests.

NodeJS Examples

Check out the contact lists tests.

PUT Example

$ curl -kvXPUT https://rest.portatext.com/contact_lists/2/contacts/12223334444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: text/csv' \
  -H'Accept: application/json'

PUT Example (With variables)

$ curl -vXPUT https://rest.portatext.com/contact_lists/2/contacts/12223334444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"variables":[{"key": "first_name", "value": "John"}]}'

DELETE Example

$ curl -kvXGET https://rest.portatext.com/contact_lists/2/contacts/12223334444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/contact_lists/:contact_list_id/contacts

Description

Import contacts to a contact list from a CSV file. If the uploaded file is accepted successfully, you will get a job_id as a result. You can use the /jobs API to check for when it's finished or check for the notification type job_status in Notifications. You can also access the contact lists in a paginated way.

Will also export the complete contact list to a CSV file when using the GET method.

NOTES:

  • On import: Use Content-Type: text/csv and Accept: application/json.
  • On export: Use Content-Type: application/json and Accept: text/csv.
  • When accessing the list by pages, use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • contact_list_id: Required. Integer. Passed in path.
  • page: Optional. Integer. Page number, passed in query string on GET.

Methods

  • PUT (Imports a CSV file to a contact list)
  • GET (Exports the contact list as a CSV)

Returns

  • 200: On success when exporting.
  • 202: On success.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid ID.

Errors

  • already_running

PHP Examples

Check out the contact lists tests.

Ruby Examples

Check out the contact lists tests.

NodeJS Examples

Check out the contact lists tests.

CSV Format

Please see "What's the CSV format that I should use to create campaigns, or import contacts, contact lists, and variables?".

PUT Example

$ curl -kvXPUT https://rest.portatext.com/contact_lists/2/contacts \
  -H'X-Api-Key: your_token' \
  --data-binary @/tmp/contacts.csv \
  -H'Content-Type: text/csv' \
  -H'Accept: application/json'

GET Example

$ curl -kvXGET https://rest.portatext.com/contact_lists/2/contacts \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

GET Example (Paginated)

$ curl -kvXGET https://rest.portatext.com/contact_lists/2/contacts?page=2 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/campaigns/:id

Description

Manages Campaigns. When creating a campaign you will get a job_id as a result. You can use the /jobs API to check for when it's finished or check for the notification type job_status in Notifications.

Check out "How are my messages billed?" for more information on how you will be charged per message sent.

Authentication methods

  • Session
  • API Key

Arguments

  • page: Optional. Integer. Page number, passed in query string on GET.
  • id: Required when operating on a specific campaign. Integer. Passed in path.
  • name: Required. String.
  • from: See same variable in /sms. Can also be an array. This will allow you to evenly balance your outbound messages or calls through different numbers.
  • type: Required. String. One of the available Campaign Types.
  • service_id: See same variable in /sms. Only available for SMS campaigns.
  • all_subscribers: Optional. Boolean. When setting service_id, set this to true to send the message to all the subscribers of the sms service. This overrides arguments like contact_list_ids and using a CSV file.
  • settings: Object. Required. Will depend on the campaign type. See Campaign Settings.
  • contact_list_ids: Required if not uploading a CSV file. Array of integers with contact list ids to include.
  • schedule: Optional. Object. A Schedule object. If you send one, be ready to handle any of the possible schedule errors.

Methods

  • POST (Creates a campaign)
  • DELETE (Deletes a campaign)
  • GET (Gets a campaign -or all campaigns- information)

Returns

  • 202: On success.
  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors (Common)

  • settings_required
  • name_already_exists
  • name_required
  • name_too_short
  • name_too_long
  • service_id_or_from_required
  • file_contact_list_or_subscribers_required
  • unknown_contact_list_ids
  • subscribers_only_allowed_with_services
  • cant_mix_subscribers_and_csv_or_contact_lists
  • unknown_service
  • disabled_service
  • If you use a schedule expect any of the possible schedule errors.

Errors (Telephony)

  • flow_required
  • flow_too_short
  • flow_too_long
  • flow_invalid
  • min_iteration_time_required
  • min_iteration_time_too_low
  • min_iteration_time_too_high
  • iterations_required
  • iterations_too_low
  • iterations_too_high
  • post_call_work_duration_required
  • post_call_work_duration_too_low
  • post_call_work_duration_too_high
  • agents_required
  • agents_too_low
  • agents_too_high
  • unknown_flow_action
  • flow_action_value_required
  • seconds_required
  • seconds_too_low
  • seconds_too_high
  • dial_timeout_required
  • dial_timeout_too_low
  • dial_timeout_too_high
  • if_human_required
  • if_machine_required
  • if_notsure_required
  • if_human_invalid
  • if_machine_invalid
  • if_notsure_invalid
  • cant_nest_amd
  • timeout_required
  • timeout_invalid
  • timeout_too_long
  • timeout_too_short
  • outbound_trunk_id_required
  • outbound_trunk_id_invalid
  • outbound_trunk_id_unknown

Errors (SMS)

  • invalid_from
  • template_id_or_text_required
  • cant_use_template_id_and_text
  • unknown_template
  • message_too_short

PHP Examples

Check out the campaigns tests.

Ruby Examples

Check out the campaigns tests.

NodeJS Examples

Check out the campaigns tests.

POST Example (For a campaign targeted to a set of contact lists)

$ curl -kvXPOST https://rest.portatext.com/campaigns \
  -H'X-Api-Key: your_token' \
  -d'{"name": "campaign name", "from": "13054591234", "contact_list_ids": [1,2,3], {"settings":{"text": "This will be sent"}}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

POST Example (For a campaign targeted to contacts in a CSV file)

$ curl -kvXPOST https://rest.portatext.com/campaigns?settings=%7B%22name%22%3A%22my+test2%22%2C%22description%22%3A%22description%22%2C%22from%22%3A%2212223334444%22%2C%22settings%22%3A%7B%22template_id%22%3A100%2C%22variables%22%3A%7B%22salutation%22%3A%22Hello%3F%22%7D%7D%7D \
  -H'X-Api-Key: your_token' \
  --data-binary @/tmp/contacts.csv \
  -H'Content-Type: text/csv' \
  -H'Accept: application/json'

GET Example (for one campaign)

$ curl -kvXGET https://rest.portatext.com/campaigns/2 \
  -H'X-Api-Key: your_token'

GET Example (for all campaigns)

$ curl -kvXGET https://rest.portatext.com/campaigns \
  -H'X-Api-Key: your_token'

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/campaigns/2 \
  -H'X-Api-Key: your_token'

NOTE: You can also send a CSV file with the list of contacts instead of a list of contact IDs. For this, you need to:

  • Set the Content-Type header to text/csv
  • Encode all the arguments for the campaign creation (id, name, from, etc) into a JSON string, and pass it on the query string as the value of the "settings" parameter (i.e: POST to /campaigns?settings=URL_ENCODED_JSON_STRING)
  • Send the CSV file as usual as the body payload.

See the campaign tests of the SDK of your language of choice for an example.

The CSV can also contain variables, here's a sample CSV payload:

number,first_name,last_name
12223334444,John,Doe
13334445555,Albert,Beckenbauer

/campaigns/:id/lifecycle

Description

Manages campaigns lifecycle (see Campaigns).

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required. Integer. Passed in path. Campaign ID.
  • action: Required. String. One of "start", "pause", "resume", "cancel".

Methods

  • POST (Changes the campaign status and update its lifecycle)

Returns

  • 200: On success.

Errors

  • invalid_action
  • unknown_campaign
  • campaign_in_wrong_state

PHP Examples

Check out the campaign lifecycle tests.

Ruby Examples

Check out the campaign lifecycle tests.

NodeJS Examples

Check out the campaign lifecycle tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/campaigns/2/lifecycle \
  -H'X-Api-Key: your_token' \
  -d'{"action": "start"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/campaigns/:id/contacts

Description

Will export the complete contact list for a campaign to a CSV file when using the GET method. You can also access the list in a paginated way.

NOTES:

  • On export: Use Content-Type: application/json and Accept: text/csv.
  • When accessing the list by pages, use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required. Integer. Campaign ID. Passed in path.
  • page: Optional. Integer. Page number, passed in query string on GET.

Methods

  • GET (Exports the contact list as a CSV or paginated list)

Returns

  • 200: On success when exporting.
  • 404: On invalid ID.

Errors

  • already_running

PHP Examples

Check out the campaigns tests.

Ruby Examples

Check out the campaigns tests.

NodeJS Examples

Check out the campaigns tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/campaigns/2/contacts \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

GET Example (Paginated)

$ curl -kvXGET https://rest.portatext.com/campaigns/2/contacts?page=2 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/campaigns/:id/contacts/:contact

Description

Avoids contacting a contact that has not been contacted yet, provided that:

  • The campaign is active, in one of the states "running" or "paused".
  • The contact hasn't been contacted yet (i.e: "pending" state).

Authentication methods

  • Sesión
  • API Key

Arguments

  • id: Required. Integer. Campaign ID. Passed in path.
  • contact: Required. Integer. Passed in path.

Methods

  • DELETE (Cancels a contact)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid Campaign ID or Contact.

Errors

  • campaign_in_wrong_state
  • contact_in_invalid_state

PHP Examples

Check out the campaigns tests.

Ruby Examples

Check out the campaigns tests.

NodeJS Examples

Check out the campaigns tests.

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/campaigns/2/contacts/12223334444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/trunks

Description

Manages trunks.

Authentication methods

  • Session
  • API Key

Arguments

  • name: Required. String.
  • ip: Required. String.

Methods

  • PUT (Updates a trunk)
  • POST (Creates a trunk)
  • GET (Gets a trunk -or all trunks- information)
  • DELETE (Deletes a trunk)

Returns

  • 200: On success.
  • 201: On new trunk creation.
  • 400: On invalid parameters (check the field error_description for details).
  • 404: On invalid ID.

Errors

  • name_or_ip_already_exists
  • name_required
  • name_too_short
  • name_too_long
  • ip_invalid

PHP Examples

Check out the trunks tests.

Ruby Examples

Check out the trunks tests.

NodeJS Examples

Check out the trunks tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/trunks \
  -H'X-Api-Key: your_token' \
  -d'{"name": "trunk_name", "ip": "1.2.3.4"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (for one trunk)

$ curl -kvXGET https://rest.portatext.com/trunks/2 \
  -H'X-Api-Key: your_token'

GET Example (for all trunks)

$ curl -kvXGET https://rest.portatext.com/trunks \
  -H'X-Api-Key: your_token'

PUT Example

$ curl -kvXPUT https://rest.portatext.com/trunks/2 \
  -H'X-Api-Key: your_token' \
  -d'{"name": "trunk_name", "ip": "1.2.3.4"}' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/trunks/2 \
  -H'X-Api-Key: your_token'

/blacklist/:number

Description

Manages a Blacklist or Don't Call List (DNC). Numbers added to this list will not receive SMS' or phone calls under any circumstances.

Authentication methods

  • Session
  • API Key

Arguments

  • number: Required when checking presence for a single contact. Integer. Passed in path.
  • page: Optional. Integer. Page number, passed in query string on GET.

Methods

  • PUT (Add a number)
  • DELETE (Deletes a number)
  • GET (Checks for a number or paginates through the blacklist)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

PHP Examples

Check out the blacklist tests.

Ruby Examples

Check out the blacklist tests.

NodeJS Examples

Check out the blacklist tests.

PUT Example

$ curl -kvXPOST https://rest.portatext.com/blacklist/1785554444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

DELETE Example

$ curl -kvXDELETE https://rest.portatext.com/blacklist/1785554444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example

$ curl -kvXGET https://rest.portatext.com/blacklist/1785554444 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

When checking if a number is present in the blacklist, a boolean field found will be returned.

GET Example (paginating the blacklist)

$ curl -kvXGET https://rest.portatext.com/blacklist?page=2\
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/blacklist/contacts

Description

Import contacts to the blacklist from a CSV file (will replace the whole list with the new one). If the uploaded file is accepted successfully, you will get a job_id as a result. You can use the /jobs API to check for when it's finished or check for the notification type job_status in Notifications.

Will also export the complete blacklist to a CSV file when using the GET method.

NOTES:

  • On import: Use Content-Type: text/csv and Accept: application/json.
  • On export: Use Content-Type: application/json and Accept: text/csv.

Authentication methods

  • Session
  • API Key

Methods

  • GET (Exports the complete blacklist to a CSV file)
  • PUT (Imports a CSV file to the blacklist)

Returns

  • 200: On success export.
  • 202: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • already_running

PHP Examples

Check out the blacklist tests.

Ruby Examples

Check out the blacklist tests.

NodeJS Examples

Check out the blacklist tests.

PUT Example

$ curl -kvXPUT https://rest.portatext.com/blacklist/contacts \
  -H'X-Api-Key: your_token' \
  --data-binary @/tmp/contacts.csv \
  -H'Content-Type: text/csv' \
  -H'Accept: application/json'

GET Example

$ curl -kvXGET https://rest.portatext.com/blacklist/contacts \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

/dids/search

Description

Searches for DIDs available to buy.

Authentication methods

  • Session
  • API Key

Arguments

  • country: Required. String. 2-letter ISO code. Passed in query string.
  • type: Optional. String. One of the available DID Types. Defaults to "any". Passed in query string.
  • page: Optional. Integer. Used to paginate results. Defaults to 1. Passed in query string.
  • where_pattern: Optional. String. One of "starts_with", "ends_with", "anywhere". Required only if "pattern" is used. Passed in query string.
  • pattern: Optional. String. A series of alpha numeric characters desired to be in the DID number. Required only if "where_pattern" is used. Passed in query string.

Methods

  • GET (Finds DIDs)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • required_where_pattern
  • required_pattern
  • invalid_where_pattern
  • invalid_page
  • invalid_country
  • required_country
  • invalid_type

PHP Examples

Check out the dids search tests.

Ruby Examples

Check out the dids search tests.

NodeJS Examples

Check out the dids search tests.

GET Example

$ curl -vXGET 'https://rest.portatext.com/dids/search?country=mx&page=2&pattern=888&type=mobile&where_pattern=anywhere' \
  -H'X-Api-Key: your_token'

/dids/:did/buy

Description

Buys a DID. You can find available DIDs by using the DID Search endpoint.

Authentication methods

  • Session
  • API Key

Arguments

  • did: Required. Integer. DID to buy, passed in path.
  • card_id: Required. Integer. A Credit Card ID previously created with the Credit Cards endpoint.

Methods

  • POST (Buys a DID)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • unknown_number
  • required_card_id
  • did_not_available

POST Example

$ curl -vXPOST https://rest.portatext.com/dids/17863338888/buy \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"card_id": 177821}'

/contacts/:number/variables/:key

Description

Gets or sets one or more variables for a given contact number.

Authentication methods

  • Session
  • API Key

Arguments

  • number: Required. Integer. Contact number.
  • key: Optional. Required when setting or removing a specific variable. String. The name of the variable.
  • value: Required when setting a variable. String.

Methods

  • GET (Retrieves one or all variables)
  • PUT (Sets one or all variables)
  • DELETE (Deletes one or all variables)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • key_required
  • value_required
  • key_too_short
  • value_too_short
  • key_too_long
  • value_too_long

PHP Examples

Check out the variables tests.

Ruby Examples

Check out the variables tests.

NodeJS Examples

Check out the variables tests.

GET Example (For all variables)

$ curl -vXGET https://rest.portatext.com/contacts/17863338888/variables \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (For one variable)

$ curl -vXGET https://rest.portatext.com/contacts/17863338888/variables/first_name \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

PUT Example (For all variables)

$ curl -vXPUT https://rest.portatext.com/contacts/17863338888/variables \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"variables":[{"key": "first_name", "value": "John"}]}'

PUT Example (For one variable)

$ curl -vXPOST https://rest.portatext.com/contacts/17863338888/variables/first_name \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"value": "John"}'

The result on error should be a status 400 and the variable list is returned in order, with an additional field named errors describing what went wrong with each one of the variables.

DELETE Example (For all variables)

$ curl -vXDELETE https://rest.portatext.com/contacts/17863338888/variables \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' 

DELETE Example (For one variable)

$ curl -vXPOST https://rest.portatext.com/contacts/17863338888/variables/first_name \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/contacts

Description

  • Import contacts and variables from a CSV file. If the uploaded file is accepted successfully, you will get a job_id as a result. You can use the /jobs API to check for when it's finished or check for the notification type job_status in Notifications. Existing variables will be replaced on success.
  • Will also export the complete variable list for all contacts to a CSV file when using the GET method.
  • Can be used to access the full contact list with pagination.

NOTES:

  • On import: Use Content-Type: text/csv and Accept: application/json.
  • On export: Use Content-Type: application/json and Accept: text/csv.
  • On pagination: Use Content-Type: application/json and Accept: application/json.

Sample CSV Content

number,first_name,last_name,title
12223334444,John,Doe,
13334445555,Albert,Murdock,Mr.

Authentication methods

  • Session
  • API Key

Arguments

  • with_contact_lists: Optional. Boolean. Passed in Query String. If present, will add a field named contact_list_ids with a CSV list of integers, where each integer is a contact list id where this contact is present. Only applies to CSV export. Contact list ids are always included when requesting a JSON response.
  • page: Optional. Integer. Passed in Query String. Only applies when paginating contacts, and not in import/export operations.

Methods

  • GET (Retrieves all contacts and variables)
  • PUT (Sets all contacts and variables)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

PHP Examples

Check out the contacts tests.

Ruby Examples

Check out the contacts tests.

NodeJS Examples

Check out the contacts tests.

GET Example (For all contacts and variables)

$ curl -vXGET https://rest.portatext.com/contacts \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

GET Example (Pagination)

$ curl -vXGET https://rest.portatext.com/contacts?page=3 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

PUT Example (For all contacts and variables)

$ curl -vXPUT https://rest.portatext.com/contacts \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: text/csv' \
  -H'Accept: application/json' \
  --data-binary @/tmp/variables.csv \

/number_verify/:id

Description

Initiates a number verification process by sending an SMS to the target number using a template. Can also be used to verify the number with a given code. Read more at:

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required. Integer. Passed in path. The target number to verify.
  • code: Required when verifying a number with a given code (GET operation). Passed in query string.
  • template_id: Required when initiating the number verification process. Passed in body. Template ID to use. The template MUST have a placeholder for the variable code to include the autogenerated code.
  • variables: Optional. Object. Used when initiating the number verification process. Passed in body. Extra variables to include in the template.
  • from: Required when initiating the number verification process. String. DID to use as source for the SMS that includes the verification code.

Methods

  • GET (Verifies a given code with the given number)
  • POST (Initiates the number verification process)
  • DELETE (Cancels the number verification process)

Returns

  • 200: On success (when verifying a number with a code).
  • 202: On success when sending the verification code.
  • 400: On invalid parameters (check the field error_description for details).

Errors

See the SMS API

PHP Examples

Check out the number verify tests.

Ruby Examples

Check out the number verify tests.

NodeJS Examples

Check out the number verify tests.

GET Example

$ curl -vXGET 'https://rest.portatext.com/number_verify/12223334444?code=123456 \
  -H'X-Api-Key: your_token'

When verifying a number, the response will include a boolean field named result. true means the code is correct.

POST Example

$ curl -vXPOST 'https://rest.portatext.com/number_verify/12223334444 \
  -H'X-Api-Key: your_token'

DELETE Example

$ curl -vXDELETE 'https://rest.portatext.com/number_verify/12223334444 \
  -H'X-Api-Key: your_token'

/inspect/:number

Description

Returns information about the given telephone number, for example:

  • Type of device (landline or mobile)
  • Mobile Country Code (MCC) and Mobile Network Code (MNC)
  • Operator information
  • Country name and ISO code

This can also be used to query multiple numbers at once by uploading a CSV and starting a Job. The result will be available via the Job Result API.

For more information about the meaning of these fields, see the "Concepts" section of our FAQ.

For more information about this feature, check out or blog post "Landline or Mobile? Lower your SMS costs and avoid fraud".

NOTES:

  • When querying multiple numbers: Use Content-Type: text/csv and Accept: application/json.
  • When querying a single number: Use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • number: Required unless uploading a CSV. Integer. Passed in path. The target number to inspect.

Methods

  • POST (Queries the given number(s))

Returns

  • 200: On success (when inspecting a single number).
  • 202: On success when uploading a CSV to start a Job for multiple numbers.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • insufficient_credit
  • number_invalid

PHP Examples

Check out the inspect tests.

Ruby Examples

Check out the inspect tests.

NodeJS Examples

Check out the inspect tests.

POST Example (Single number)

$ curl -vXPOST 'https://rest.portatext.com/inspect/12223334444 \
  -H'X-Api-Key: your_token' \
  -H'Accept: application/json'
  -H'Content-Type: application/json'

POST Example (Multiple numbers)

$ curl -vXPOST 'https://rest.portatext.com/inspect \
  -H'X-Api-Key: your_token' \
  -H'Accept: application/json'
  -H'Content-Type: text/csv'

/sms_services/:id

Description

Manages SMS Services.

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required. Integer. Passed in path.

Methods

  • GET (Retrieves one or all of the available SMS Services).

Returns

  • 200: On success (when verifying a number with a code).

PHP Examples

Check out the sms services tests.

Ruby Examples

Check out the sms services tests.

NodeJS Examples

Check out the sms services tests.

GET Example (All SMS Services).

$ curl -vXGET 'https://rest.portatext.com/sms_services \
  -H'X-Api-Key: your_token'

GET Example (One SMS Service).

$ curl -vXGET 'https://rest.portatext.com/sms_services/55 \
  -H'X-Api-Key: your_token'

/sms_services/:id/subscribers

Description

Export subscribers to a CSV file or paginates them.

NOTES:

  • When exporting to a CSV file, use Content-Type: application/json and Accept: text/csv.
  • When accessing the list by pages, use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • id: Required. Integer. Passed in path.
  • page: Optional. Integer. Page number, passed in query string on GET.

Methods

  • GET (Exports the list as a CSV or paginates them)

Returns

  • 200: On success when exporting.
  • 404: On invalid ID.

PHP Examples

Check out the sms services tests.

Ruby Examples

Check out the sms services tests.

NodeJS Examples

Check out the sms services tests.

GET Example (For CSV Export)

$ curl -kvXGET https://rest.portatext.com/sms_services/55/subscribers \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

GET Example (For pagination)

$ curl -kvXGET https://rest.portatext.com/sms_services/55/subscribers?page=3 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: text/csv' \
  -H'Accept: application/json'

/version

Description

Returns version information for server, tools, and components (because we ❤️ :neckbeard: 's !)

Authentication methods

  • Session
  • API Key

Arguments

Methods

  • GET (Returns information)

Returns

  • 200: On success.

PHP Examples

Check out the version tests.

Ruby Examples

Check out the version tests.

NodeJS Examples

Check out the version tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/version \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/operators

Description

Returns worldwide known mobile operators, their country, and their network code. Supports exporting the list to CSV.

NOTES:

  • On export: Use Content-Type: application/json and Accept: text/csv.
  • When accessing the list by pages, use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • page: Optional. Integer. Page number, passed in query string on GET.
  • sort_by: Optional. String. One of country, mcc.
  • order: Optional. String. One of asc, desc.

Methods

  • GET (Returns information)

Returns

  • 200: On success.

PHP Examples

Check out the operators tests.

Ruby Examples

Check out the operators tests.

NodeJS Examples

Check out the operators tests.

GET Example (Paginated)

$ curl -kvXGET https://rest.portatext.com/operators?page=10&sort_by=country&order=desc \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (CSV Export)

$ curl -kvXGET https://rest.portatext.com/operators \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

/destinations

Description

Returns all known destinations. Supports exporting the list to CSV.

NOTES:

  • On export: Use Content-Type: application/json and Accept: text/csv.
  • When accessing the list by pages, use Content-Type: application/json and Accept: application/json.

Authentication methods

  • Session
  • API Key

Arguments

  • page: Optional. Integer. Page number, passed in query string on GET.
  • sort_by: Optional. String. One of country, destination.
  • order: Optional. String. One of asc, desc.

Methods

  • GET (Returns information)

Returns

  • 200: On success.

PHP Examples

Check out the destinations tests.

Ruby Examples

Check out the destinations tests.

NodeJS Examples

Check out the destinations tests.

GET Example (Paginated)

$ curl -kvXGET https://rest.portatext.com/destinations?page=10&sort_by=country&order=desc \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (CSV Export)

$ curl -kvXGET https://rest.portatext.com/destinations \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

/simulate

Description

Provides a way to simulate the sending of a message. Test your text (and/or templates with variables) before sending them so you know in advance things like encoding needed, number of segments, total cost, cost per destination, etc.

Authentication methods

  • Session
  • API Key

Arguments

  • country: Required. String. Passed in query string. 2-letter ISO code for the destination country.
  • template_id: Passed in query string. See same variable in /sms.
  • text: Passed in query string. See same variable in /sms.
  • variables: Passed in query string. See same variable in /sms.

Methods

  • GET (Returns information)

Returns

  • 200: On success.

PHP Examples

Check out the simulate tests.

Ruby Examples

Check out the simulate tests.

NodeJS Examples

Check out the simulate tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/simulate?country=us&text=this+is+a+text \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/summary

Description

Returns a summary of usage for your account. Allows exporting the result to CSV.

NOTES:

  • On export to CSV: Use Content-Type: application/json and Accept: text/csv.

Authentication methods

  • Session
  • API Key

Arguments

  • date_from: Optional. String in format (yyyy-mm-ddTHH:MM:SS) Time zone is assumed to be the one for the account.
  • date_to: Optional. String in format (yyyy-mm-ddTHH:MM:SS) Time zone is assumed to be the one for the account.
  • granularity: Optional. String. One of: "month", "day", "week". Not available for CSV export.

Methods

  • GET (Returns information)

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

Errors

  • date_from_bigger_than_to
  • granularity_invalid

PHP Examples

Check out the summary tests.

Ruby Examples

Check out the summary tests.

NodeJS Examples

Check out the summary tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/summary?date_from=2015-01-01T00:00:00 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (CSV Export)

$ curl -kvXGET https://rest.portatext.com/summary \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: text/csv'

/gsm_charset

Description

Returns the complete GSM 03.38 character set.

Authentication methods

  • Session
  • API Key

Arguments

Methods

  • GET (Returns characters)

Returns

  • 200: On success.

PHP Examples

Check out the gsm_charset tests.

Ruby Examples

Check out the gsm_charset tests.

NodeJS Examples

Check out the gsm_charset tests.

GET Example

$ curl -kvXGET https://rest.portatext.com/gsm_charset \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/sounds/:id

Description

Manages sounds for Telephony Campaigns.

Authentication methods

  • Session
  • API Key

NOTES:

  • On exporting a sound file: Use Content-Type: application/json and Accept: audio/mpeg.
  • When uploading a sound file (via PATCH or POST): Use Content-Type: audio/mpeg and Accept: application/json.
  • When updating a sound (via PATCH) without the sound file: Use Content-Type: application/json and Accept: application/json.
  • Note that this endpoint supports PATCH, so when updating a sound you can change only one, or some, or all of its properties. For example, only the sound (binary) data, or just the name, or all of them at once.

Arguments

  • id: Optional. Integer. Passed in path.
  • name: Optional on PATCH, Required on POST. String. Passed in query string.
  • description: Optional on PATCH, Required on POST. String. Passed in query string.

Methods

  • GET
  • PATCH
  • DELETE

Returns

  • 200: On success.
  • 400: On invalid parameters (check the field error_description for details).

PHP Examples

Check out the sounds tests.

Ruby Examples

Check out the sounds tests.

NodeJS Examples

Check out the sounds tests.

POST Example (Creates a new sound)

$ curl -kvXPOST https://rest.portatext.com/sounds?name=first+sound&description=some+description \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: audio/mpeg' \
  -H'Accept: application/json' \
  --data-binary @/sound1.mp3

PATCH Example (Updates a sound info but not the sound file)

$ curl -kvXPATCH https://rest.portatext.com/sounds/123?name=first+sound&description=some+description \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  --data-binary @/sound1.mp3

PATCH Example (Updates a sound info AND the sound file)

$ curl -kvXPATCH https://rest.portatext.com/sounds/123?name=first+sound&description=some+description \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: audio/mpeg' \
  -H'Accept: application/json' \
  --data-binary @/sound1.mp3

GET Example (Downloading sound)

$ curl -kvXGET https://rest.portatext.com/sounds/123 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: audio/mpeg'

GET Example (Getting sound info)

$ curl -kvXGET https://rest.portatext.com/sounds/123 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

GET Example (all sounds)

$ curl -kvXGET https://rest.portatext.com/sounds\
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

DELETE Example (Deletes a sound)

$ curl -kvXDELETE https://rest.portatext.com/sounds/123 \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/plans

Description

Gets all available plans.

Authentication methods

  • None

Methods

  • GET

Returns

  • 200: On success.

PHP Examples

Check out the plans tests.

Ruby Examples

Check out the plans tests.

NodeJS Examples

Check out the plans tests.

GET Example (all plans)

$ curl -kvXGET https://rest.portatext.com/plans\
  -H'Content-Type: application/json' \
  -H'Accept: application/json'

/calls

Description

Issues a telephony call or searches for previous calls.

Authentication methods

  • Session
  • API Key

Arguments (for POST, sent on body)

  • to: Required. String. In E164 format (i.e: US numbers with the leading "1", etc).
  • from: Required. String. DID to use. In E164 format (i.e: US numbers with the leading "1", etc). You can also send an array of DIDs and one will be selected at random from those. If you send the keyword "any", a random DID will be selected from the ones available in your account.
  • See the arguments for telephony settings in the Campaign API.

Arguments (for GET, sent on query string)

  • page: Optional. Integer. Page number for results.
  • from: Optional. String. Source telephone number in E164 (no leading '+').
  • to: Optional. String. Target telephone number in E164 (no leading '+').
  • date_from: Optional. String in format (yyyy-mm-ddTHH:MM:SS) Time zone is assumed to be the one for the account.
  • date_to: Optional. String in format (yyyy-mm-ddTHH:MM:SS) Time zone is assumed to be the one for the account.
  • sort_order: Optional. String. One of: asc, desc.
  • sort_field: Optional. String. Currently the only value supported is date.
  • campaign_id: Optional. Integer. The ID of one of your Campaigns.

Methods

  • POST (Issues a call)
  • GET (Searches for Call operations)

Returns

  • 202: On success (POST).
  • 400: On invalid parameters (check the field error_description for details).
  • 402: On insufficient credits for the requested operation.

Errors (POST)

Errors (GET)

  • date_from_bigger_than_to
  • campaign_id_invalid
  • sort_order_invalid
  • sort_field_invalid
  • date_from_invalid
  • date_to_invalid

PHP Examples

Check out the calls tests.

Ruby Examples

Check out the calls tests.

NodeJS Examples

Check out the calls tests.

POST Example

$ curl -kvXPOST https://rest.portatext.com/sms \
  -H'X-Api-Key: your_token' \
  -H'Content-Type: application/json' \
  -H'Accept: application/json' \
  -d'{"from": ["17862223333"], "to": "13053334444", "outbound_trunk_id": 12, "dial_timeout": 30, "flow": [{"forward": {"trunk_id": 12, "timeout": 30}}]}'
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.