API v1 spec

gistfile1.txt

Authentication: pass your api token in the 'X-ACCESS-TOKEN' request header, or in the 'api_token' parameter


Create a user

POST 
onboardiq.com/api/v1/applicants
Required attributes: [name, email, phone]
Email must be valid and unique
Phone must be unique
'Key' is reserved for our identifier
All keys at the root level.

Examples:

POST onboardiq.com/api/v1/applicants
{
  api_token: 'uJD0qSxq7-gEJLViY1-ITg',
  name: 'John',
  email: '[email protected]',
  phone: '5034834844',
  any: 'other',
  keys: 'that you might want',
  address[street]: '123 main st',
  address[city]: 'San Francisco, CA'
}

Response:
200 OK
{
name: "John",
email: "[email protected]",
phone: "5034834844",
any: "other",
keys: 'that you might want',
address: {
    street: "123 main st",
    city: "San Francisco, CA"
  },
key: "deb3648f",
created_at: "2014-10-05T19:14:36.175Z"
}

Invalid api_token: 404 NOT FOUND

Invalid data: 422 UNPROCESSABLE ENTITY

{
  -errors: {
    -email: [
      "can't be blank"
      "is invalid"
    ]
    -name: [
      "can't be blank"
    ]
    -phone: [
      "can't be blank"
    ]
  }
}


Update an applicant

Very similar to post
PUT
onboardiq.com/api/v1/applicants/:key
Name, Email, Phone are not required. If they are passed the applicant will be validated with the new values.
Existing attributes are overwritten (except key, created_at), and new attributes are added.


Example
PUT onboardiq.com/api/v1/applicants/deb3648f
{
  api_token: 'uJD0qSxq7-gEJLViY1-ITg',
  name: 'Johnny',
  address[city]: 'San Francisco',
  address[state]: 'CA'
}

Response:
200 OK
{
name: "Johnny",
email: "[email protected]",
phone: "5034834844",
any: "other",
keys: 'that you might want',
address: {
    street: "123 main st",
    city: "San Francisco, CA",
    state: "CA"
  },
key: "deb3648f",
created_at: "2014-10-05T19:14:36.175Z"
}

Invalid key -> 404
Invalid attributes -> 422 + error hash



Getting information on an applicant

GET
onboardiq.com/api/v1/applicants/:key

Example
GET onboardiq.com/api/v1/applicants/deb3648f?api_token=uJD0qSxq7-gEJLViY1-ITg

Response:
200 OK
{
name: "Johnny",
email: "[email protected]",
phone: "5034834844",
any: "other",
keys: 'that you might want',
address: {
    street: "123 main st",
    city: "San Francisco, CA",
    state: "CA"
  },
key: "deb3648f",
created_at: "2014-10-05T19:14:36.175Z"
}



List all applicants in my account

GET
onboardiq.com/api/v1/applicants

Returns an array of applicant objects

Example
GET onboardiq.com/api/v1/applicants?api_token=uJD0qSxq7-gEJLViY1-ITg


Response:
[
  {
  name: "Johnny",
  email: "[email protected]",
  phone: "5034834844",
  any: "other",
  keys: 'that you might want',
  address: {
      street: "123 main st",
      city: "San Francisco, CA",
      state: "CA"
    },
  key: "deb3648f",
  created_at: "2014-10-05T19:14:36.175Z"
  },
  {
    name: "Sarah",
    email: "[email protected]",
    phone: "2380038333",
    address: {
        street: "1001 W Fillmore St",
        city: "Oakland",
        state: "CA"
      },
    availablity_string: "Evenings"
    key: "26e084a5",
    created_at: "2014-10-10T19:14:36.175Z"
  }
]

@jeffrwells Sweet! I tried these out in postman! Couple questions:

1. is passing api token in url params dangerous? is that why a lot of times you have an app key and a secret key?
2. what's an example of how a user using rails could post and get from our api?
3. when they want us to push user data everytime their state changes, how would they do that? Would we need to provide the option of adding webhooks at each stage and having them submit their hook_url?
   -> mainly, if customer interface looks like: https://cloud.githubusercontent.com/assets/1287173/4520142/0a3cc35a-4cdc-11e4-876c-39eab692af2d.PNG

they would want those statuses to show updates, and would need us to send the updated status info

1. Should be fine, especially over https
2. Look at HTTParty or Curb
3. Ya that would be a webhook, we need queuing and Module for that