Skip to content

Instantly share code, notes, and snippets.

@beneggett

beneggett/savvi-membership-api.md

Last active December 25, 2015 05:38
Show Gist options
  • Save beneggett/6925485 to your computer and use it in GitHub Desktop.
Save beneggett/6925485 to your computer and use it in GitHub Desktop.
Download ZIP
Savvi Wholesale Partners API
Raw
savvi-membership-api.md

Savvi Membership API for Wholesale Partners

This guide covers the inner working of Savvi's RESTful API. It assumes a basic understanding of the principles of REST.

The REST API is designed to give developers a convenient way to access data contained within Savvi. As Savvi continues to grow, the API will continue to be developed.

Making an API Call

Savvi provides a staging and production URL for creating users.

Staging URL: http://www.savvi-staging.com/api/v1/

Production URL: https://www.savvi.com/api/v1/

You will need an authentication token to access the API. If you have not received one, please contact Savvi and we will provide one for you.

Rules

The following are some simple rules that all Savvi API endpoints comply with.

  1. All successful requests for the API will return a status of 200.
  2. Both create and update requests will return Savvi's representation of the data upon success.
  3. If a create or update request fails, a status code of 422 will be returned, with a hash containing an "error" key, and an "errors" key. The errors value will contain all ActiveRecord validation errors encountered when saving this record.
  4. Delete requests will return status of 200, and no content.
  5. If a resource can not be found, the API will return a status of 404.

API Communication Methods

Savvi API supports three common communication methods:

  • HTTP
  • JSON
  • XML

HTTP Data

Developers communicate with the Savvi API using the HTTP Requests. Requests for data are communicated in the standard manner using the HTTP protocol.

JSON Data

Developers communicate with the Savvi API using the JSON data format. Requests for data are communicated in the standard manner using the HTTP protocol.

XML Data

Developers communicate with the Savvi API using the XML data format. Requests for data are communicated in the standard manner using the HTTP protocol.

Creating Wholesale Members via API

URL Path: /api/v1/create_wholesale_member

A wholesale member can be created by posting the the URL path shown above. A standard post includes your Authentication token, and a users block with nested address block and associated parameters:

Fields Needed for Savvi Users:

All fields that are denoted as required validate the presence of those attributes.

Authentication Token:

:authentication_token | Required | String (provided by Savvi)

User block:

:email                 | Required | String (Validates valid email format with regexp: /^([\w\.%\+\-]+)@([\w\-]+\.)+([\w]{2,})$/i )
:password              | Optional | String (Validates length is 6-128 characters, otherwise Savvi will generate for user)
:first_name            | Required | String 
:last_name             | Required | String
:username              | Optional | String (Must be Unique if present)
:date_of_birth         | Optional | Date   (Validates format should be "YYYY-MM-DD")
:gender                | Optional | String ("Male", "Female", "Prefer not to say")

Address block:

:address_1           | Required | String 
:address_2           | Optional | String 
:address_3           | Optional | String 

:city                | Required | String
:state               | Required | String (Two Digit State Code. Full mapping: https://gist.github.com/beneggett/431b56cd26f8ca32afce )
:zipcode             | Required | String

:country             | Optional | String (Will default to "United States of America", as Savvi is currently only available in the US)
:phone               | Required | String (Validates that its a valid 10 digit US phone number according to regexp: /\A\s*(?:(?:\(1\)|1)\s?-?\s?)?(?:[2-9][0-9]{2}|\([2-9][0-9]{2}\))\s?-?\s?[2-9][0-9]{2}\s?-?\s?[0-9]{4}\s*\Z/ )
                                  # Examples of phone numbers that match:
                                  #   14045550123
                                  #   1-4045550123
                                  #   (1)4045550123
                                  #   (1)-4045550123
                                  #   1 4045550123
                                  #   1 -4045550123
                                  #   1 - 4045550123
                                  #   (1) 4045550123
                                  #   (1) -4045550123
                                  #   (1) - 4045550123
                                  #   4045550123
                                  #   1 (404)5550123
                                  #   1 (404) 5550123
                                  #   1 (404)-5550123
                                  #   1 (404) - 5550123
                                  #   1 (404) 555-0123
                                  #   1 (404) 555 - 0123
                                  # Numbers that start with a 0 or 1 in the area code or first three locale digits would fail.

(Address values will need to be passed in an :address_attributes block, see examples below)

Responses

Savvi will respond to your post in one of three ways:

  • 200 Ok: Success. User < Email Address > created by < Your Account Name >"
  • 422: Unprocessable Entity. Appropriate Errors will be returned.
  • 401: Unauthorized

Upon successful creation, an account will be setup within Savvi under your account. You can view your enrollees through your profile at www.savvi.com/profile

Create User via HTTP method & Sample

May be accessed via the browser or command line.

http://www.savvi-staging.com/api/v1/create_wholesale_member?authentication_token=AzXimVQyVqgDtRiGd3EH&user[email][email protected]&user[password]=pass1234&user[first_name]=testFirst&user[last_name]=TestLast&user[status]=active&user[address_attributes][address1]=123 fk st&user[address_attributes][city]=Salt Lake City&user[address_attributes][state]=UT&user[address_attributes][zipcode]=84101&user[address_attributes][phone]=8015555555
curl --data "authentication_token=AzXimVQyVqgDtRiGd3EH&user[email][email protected]&user[password]=pass1234&user[first_name]=testFirst&user[last_name]=TestLast&user[status]=active&user[username]=Testusername&user[date_of_birth]=1970-07-25&user[gender]=Female&user[address_attributes][address1]=123 fk st&user[address_attributes][city]=Salt Lake City&user[address_attributes][state]=UT&user[address_attributes][zipcode]=84101&user[address_attributes][phone]=8015555555" http://www.savvi-staging.com/api/v1/create_wholesale_member

Expanded for readability:

http://www.savvi-staging.com/api/v1/create_wholesale_member?
authentication_token=AzXimVQyVqgDtRiGd3EH
&user[email][email protected]
&user[password]=pass1234
&user[first_name]=Testfirst
&user[last_name]=Testlast
&user[status]=active
&user[username]=Testusername
&user[date_of_birth]=1970-07-25
&user[gender]=Female
&user[address_attributes][address1]=123 fk st
&user[address_attributes][city]=Salt Lake City
&user[address_attributes][state]=UT
&user[address_attributes][zipcode]=84101
&user[address_attributes][phone]=8015555555

Create User via JSON & Sample

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"authentication_token":"AzXimVQyVqgDtRiGd3EH", "user":{"email":"[email protected]", "password":"pass1234", "first_name":"Testfirst", "last_name":"Testlast", "status":"active",  "username":"Testusername", "date_of_birth":"1970-07-25", "gender":"Female", "address_attributes":{"address1":"123 e Main Street", "address2":"", "address3":"", "address_type":"billing", "city":"Salt Lake City", "country":"United States", "county":"", "phone":"8015554312", "state":"UT", "zipcode":"84101"} } }' http://www.savvi-staging.com/api/v1/create_wholesale_member

Expanded for readability:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{ 
  "authentication_token":"AzXimVQyVqgDtRiGd3EH", 
  "user":{ 
    "email":"[email protected]", 
    "password":"pass1234",  
    "first_name":"Testfirst", 
    "last_name":"Testlast", 
    "status":"active", 
    "username":"Testusername",
    "date_of_birth":"1970-07-25",
    "gender":"Female",
    "address_attributes":{ 
      "address1":"123 e Main Street", 
      "address2":"", 
      "address3":"", 
      "address_type":"billing", 
      "city":"Salt Lake City", 
      "country":"United States", 
      "county":"", 
      "phone":"8015554312", 
      "state":"UT", 
      "zipcode":"84101"
    }
  }
}' http://www.savvi-staging.com/api/v1/create_wholesale_member

Create User via XML & Sample

curl -v  -H "Content-Type: application/xml" -X POST  -d   "<?xml version="1.0" encoding="UTF-8" ?> <user> <email>[email protected]</email> <password>pass1234</password> <first_name>Testfirst</first_name> <last_name>Testlast</last_name> <username>apitester</username> <status>active</status>  <username>Testusername</username> <date_of_birth>1970-07-25</date_of_birth> <gender>Female</gender> <address_attributes> <address1>123 e Main Street</address1> <address2></address2> <address3></address3> <address_type>billing</address_type> <city>Salt Lake City</city> <country>United States</country> <county></county> <phone>8015554312</phone> <state>UT</state> <zipcode>84101</zipcode> </address_attributes> </user> " http://www.savvi-staging.com/api/v1/create_wholesale_member?authentication_token=AzXimVQyVqgDtRiGd3EH

Expanded for readability:

curl -v  -H "Content-Type: application/xml" -X POST  -d   "
  <?xml version="1.0" encoding="UTF-8" ?>
    <user>
      <email>[email protected]</email>
      <password>pass1234</password>
      <first_name>Testfirst</first_name>
      <last_name>Testlast</last_name>
      <username>apitester</username>
      <status>active</status>
      <username>Testusername</username>
      <date_of_birth>1970-07-25</date_of_birth>
      <gender>Female</gender>
      <address_attributes>
        <address1>123 e Main Street</address1>
        <address2></address2>
        <address3></address3>
        <address_type>billing</address_type>
        <city>Salt Lake City</city>
        <country>United States</country>
        <county></county>
        <phone>8015554312</phone>
        <state>UT</state>
        <zipcode>84101</zipcode>
      </address_attributes>
    </user>
" http://www.savvi-staging.com/api/v1/create_wholesale_member?authentication_token=AzXimVQyVqgDtRiGd3EH

Updating Wholesale Members via API

URL Path: /api/v1/update_wholesale_member

A wholesale member can be updated by posting the the URL path shown above. Please note, wholesale partners may only update wholesale members for whom they are the direct sponsor. A standard post includes your Authentication token, the users email you want to update, and a users block with nested address block and associated parameters:

Fields Needed for Savvi Users:

Authentication Token:

:authentication_token | Required | String (Provided by Savvi.)

Email Address of User to update:

:email | Required | String

User block:

Any/All fields are optional.

:email                 | Optional | String
:password              | Optional | String (minimum 7 characters)
:first_name            | Optional | String
:last_name             | Optional | String
:username              | Optional | String
:date_of_birth         | Optional | Date "YYYY-MM-DD" format
:gender                | Optional | String ("Male", "Female", "Prefer not to say")
:status                | Optional | String ("active", "inactive", "banned")

Address block:

:address_1           | Optional | String
:address_2           | Optional | String 
:address_3           | Optional | String 

:city                | Optional | String
:state               | Optional | String (Two Digit State Code)
:zipcode             | Optional | String

:country             | Optional | String (Will default to "United States of America", as Savvi is currently only available in the US)
:phone               | Optional | String

(Address values will need to be passed in an :address_attributes block, see examples below)

Responses

Savvi will respond to your post in one of three ways:

  • 200 Ok: Success. User < Email Address > created by < Your Account Name >"
  • 422: Unprocessable Entity. Appropriate Errors will be returned.
  • 401: Unauthorized

Upon successful creation, an account will be setup within Savvi under your account. You can view your enrollees through your profile at www.savvi.com/profile

Update User via HTTP method & Sample

May be accessed via the browser or command line.

http://www.savvi-staging.com/api/v1/update_wholesale_member?authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]&user[address_attributes][phone]=8015555555
curl --data "authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]&user[address_attributes][phone]=8015555555" http://www.savvi-staging.com/api/v1/update_wholesale_member

Expanded for readability:

http://www.savvi-staging.com/api/v1/update_wholesale_member?
authentication_token=AzXimVQyVqgDtRiGd3EH
&[email protected]
&user[address_attributes][phone]=8015555555

Update User via JSON & Sample

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"authentication_token":"AzXimVQyVqgDtRiGd3EH", "email":"[email protected]", "user":{"address_attributes":{"phone":"8015555555"} } }' http://www.savvi-staging.com/api/v1/update_wholesale_member

Expanded for readability:

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{
  "authentication_token":"AzXimVQyVqgDtRiGd3EH",
  "email":"[email protected]", 
  "user":{
    "address_attributes":{
      "phone":"8015555555"
    } 
  } 
}' http://www.savvi-staging.com/api/v1/create_wholesale_member

Update User via XML & Sample

curl -v  -H "Content-Type: application/xml" -X POST  -d   "<?xml version="1.0" encoding="UTF-8" ?> <user> <address_attributes> <phone>8015555555</phone> </address_attributes> </user> " http://www.savvi-staging.com/api/v1/update_wholesale_member?authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]

Expanded for readability:

curl -v  -H "Content-Type: application/xml" -X POST  -d   "
  <?xml version="1.0" encoding="UTF-8" ?>
    <user>
      <address_attributes>
        <phone>801555555</phone>
      </address_attributes>
    </user>
" http://www.savvi-staging.com/api/v1/update_wholesale_member?authentication_token=AzXimVQyVqgDtRiGd3EH&[email protected]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment