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"
  }
]

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