icon_qa

INTRODUZIONE API REST

Usi l'app Postman?
 

PHONEBOOK CONTACTS

Contact search

Contact search

URI

GET https://api.smshosting.it/rest/api/phonebook/contact/search

Request

ParameterMandatoryTypeDescription
name Yes String

Full contact name

The search is performed on the fields name and lastname

offset No Integer

index of first result returned

Example:

If the search finds 100 text messages, and the field offset is set with value 50 and the field limit is set with value 10 the result contains text messages from 51 to 60

Default : 0

limit No Integer

Number of items returned.

Default : 20

Response

HTTP Status Code

CodeDescription
200 ok
400

invalid parameters

Possible errorMsg are:

NO_PARAMS - no name specified

401 Bad credentials
405 HTTP method not allowed
500 Generic error

The call returns a list of contacts in your address book.

PropertyDescription
contacts

Contacts list

For details about properties of each contact check the function Contact detail.

metadata

Metadata useful for pagination

For further details on pagination visit pagination details

 Example:

curl --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/phonebook/contact/search?name=Mario
{
   "metadata":{
      "count":1,
      "offset":0,
      "limit":20
   },
   "contacts":[
      {
         "msisdn":"393480000000",
         "name":"Mario",
         "lastname":"Rossi",
         "address":"via Italia 1",
         "city":"Roma",
         "postCode":00144,
         "province":"RM",
         "country":"IT",
         "email":"mario.rossi@fake.it",
         "homePhoneNumber":"",
         "groups":[
            {
               "id":13197,
               "name":"Amici"
            },
            {
               "id":1947,
               "name":"Lavoro"
            }
         ]
      }
   ]
}

Contact detail

contact informations

URI

GET https://api.smshosting.it/rest/api/phonebook/contact/{msisdn}

Request

ParameterMandatoryTypeDescription
msisdn Yes(must be specified on URI) String Full GSM number (including country prefix)

Response

HTTP Status Code

CodeDescription
200 ok
401 Bad credentials
404 Contact not found
405 HTTP method not allowed
500 Generic error

Property contatto:

PropertyDescription
msisdn contact phone number
name Contact name
lastname Contact surname
address Address
city City
postCode Postal code
province Province
country

country identifier 2 digit code ISO 3166 alpha-2

For example IT (Italy), US (United States)

email Email address
homePhoneNumber Phone
groups

Contact groups list

for each group is reported the internal id and field name

 Example:

curl --user AUTH_KEY:AUTH_SECRET  https://api.smshosting.it/rest/api/phonebook/contact/393480000000
   {
         "msisdn":"393480000000",
         "name":"Mario",
         "lastname":"Rossi",
         "address":"via Italia 1",
         "city":"Roma",
         "postCode":00144,
         "province":"RM",
         "country":"IT",
         "email":"mario.rossi@fake.it",
         "homePhoneNumber":"",
         "groups":[
            {
               "id":13197,
               "name":"Friends"
            },
            {
               "id":1947,
               "name":"Work"
            }
         ]
      }

New contact

Add contact to phonebook

URI

POST https://api.smshosting.it/rest/api/phonebook/contact

Request

  "Content-Type" for POST requests must be "application/x-www-form-urlencoded"
ParameterMandatoryTypeDescription
msisdn Yes String Full GSM number (including country prefix)
name Yes String Contact name
lastname No String Contact surname
address No String Address
city No String City
postCode No Integer Postal code
province No String Provincie
country No String

country identifier 2 digit code ISO 3166 alpha-2

For example IT (Italy), US (United States)

email No String Email address
homePhoneNumber No String Phone
groupsId No String

group internal id that you want associate to the contact

It's possible to specify multiple groups using comma "," as separator.

Example:

1245 or 1245,3432

Response

HTTP Status Code

CodeDescription
200 ok
400

invalid parameters

Possible errorMsg are:

BAD_CONTACT_NAME - missing parameter name

BAD_CONTACT_MSISDN - missing or invalid field msisdn

BAD_CONTACT_COUNTRY - Country code not valid

BAD_CONTACT_GROUP - Group not valid

CONTACT_ALREADY_EXISTS - Contact already present, duplicate msisdn

401 Bad credentials
405 HTTP method not allowed
500 Generic error

If the contact is successfully created you obtain a HTTP status 200 and contact details

For further details on contact properties contact detail.

 Example:

curl --user AUTH_KEY:AUTH_SECRET  -XPOST https://api.smshosting.it/rest/api/phonebook/contact \
-d "msisdn=393480000000" \
-d "name=Mario" \
-d "lastname=Rossi"
{
   "msisdn":"393480000000",
   "name":"Mario",
   "lastname":"Rossi",
   "postCode":0,
   "groups":[
      {
         "id":-1,
         "name":"NOTASSIGNED"
      }
   ]
}

Contact update

Updata a contact present on phonebook

URI

PUT https://api.smshosting.it/rest/api/phonebook/contact/{msisdn}

Request

  "Content-Type" for POST requests must be "application/x-www-form-urlencoded"
ParameterMandatoryTypeDescription
msisdn Yes(must be specified on URI) String Full GSM number (including country prefix)
name Yes String Contact name
lastname No String Contact surname
address No String Address
city No String City/td>
postCode No Integer Postal code
province No String Province
country No String Country
email No String Email address
homePhoneNumber No String Phone
groupsId No String

group internal id that you want associate to the contact

It's possible to specify multiple groups using comma "," as separator.

Example:

1245 or 1245,3432

Response

HTTP Status Code

CodeDescription
200 ok
400

Invalid parameter

Possible errorMsg are

BAD_CONTACT_NAME - missing parameter name

BAD_CONTACT_MSISDN - missing or invalid parameter msisdn

BAD_CONTACT_COUNTRY - Country code not valid

BAD_CONTACT_GROUP - Invalid group

CONTACT_ALREADY_EXISTS - Contact already present, duplicate msisdn

401 Bad credentials
405 HTTP method not allowed
500 Generic error

If the contact is successfully updated you obtain a HTTP status 200

 Example:

curl --user AUTH_KEY:AUTH_SECRET  -XPUT https://api.smshosting.it/rest/api/phonebook/contact/393480000000 \
-d "name=Mario" \
-d "lastname=Bianchi"
HTTP status 200

Elimina contatto

Eliminare un contatto in rubrica

URI

DELETE https://api.smshosting.it/rest/api/phonebook/contact/{msisdn}

Request

ParameterMandatoryTypeDescription
msisdn Yes(must be specified on URI) String Full GSM number (including country prefix)

Response

HTTP Status Code

CodeDescription
204 ok
401 Bad credentials
404 Contact not found
405 HTTP method not allowed
500 Generic error

If the contact is successfully deleted you obtain a HTTP status 204

 Example:

curl --user AUTH_KEY:AUTH_SECRET  -XDELETE https://api.smshosting.it/rest/api/phonebook/contact/393480000000
HTTP status 204