People

Note the API is currently in beta and is disabled by default. Breaking changes may occur as we finalise the functionality.
Contact us if you want to test the API and we'll turn it on for your account.

Attributes

Basic attributes

This is the data returned from people listings.

• id - The ID of the person
• user_id - If the person can login, this is their unique ID across accounts, otherwise null
• firstname - Their firstname
• surname - Their surname
• email - Their email address
• administrator - boolean value denoting whether or not they are an administrator for the account
• company - The company they belong to
• job_title - Their job-title
• department - The department they belong to
• created_at - When they were added to the account

Extended attributes

When getting a specific person, more information is returned:

• skype - Skye address
• mobile_phone - Mobile phone number
• home_phone - Home phone number
• work_phone - Work phone number
• address - Their address
• timezone - Their timezone (or the account default if they haven't set one)
• week_start - The week start day for calendars (or the account default if they haven't set one)

List People

GET https://acme.minutebase.com/api/v1/people

Response

{
    "current_page":1,
    "per_page":25,
    "total_entries":1563,
    "total_pages":63,
    "results": [
        {
            "id":"4df2b437cf02a319a90009ea",
            "user_id":"4df2b437cf02a319a90009eb",
            "firstname":"Richard",
            "surname":"Livsey",
            "email":"richard@minutebase.com",
            "administrator":true,
            "company":"MinuteBase",
            "department":null,
            "job_title":"Co-Founder",
            "created_at":1307751479
        }
    ]
}

Get Person

GET https://acme.minutebase.com/api/v1/people/:person_id

Response

{
    "address":null,
    "administrator":true,
    "company":"MinuteBase",
    "created_at":1307751479,
    "department":null,
    "email":"richard@minutebase.com",
    "firstname":"Richard",
    "home_phone":null,
    "id":"4df2b437cf02a319a90009ea",
    "job_title":"Co-Founder",
    "mobile_phone":"07841260797",
    "skype":"rlivsey",
    "surname":"Livsey",
    "timezone":"London",
    "user_id":"4df2b437cf02a319a90009eb",
    "week_start":0,
    "work_phone":null
}

Add Person

POST https://acme.minutebase.com/api/v1/people

Input

POST the attributes of the new person as a JSON document.
Note that you must be an administrator of the account to set/change the administrator status of a person.
Only firstname or surname are required, the rest of the fields are optional.
If provided, email must be unique to the account.

{
    "firstname":"Bob",
    "surname":"Tester",
    "email":"bob@example.com",
    "company":"MinuteBase",
    "department":"Testers",
    "job_title":"Head of Testing",
    "administrator":true
}

Response

{
    "id":"4df2b437cf02a319a90009ea",
    "user_id":null,
    "firstname":"Bob",
    "surname":"Tester",
    "email":"bob@example.com",
    "company":"MinuteBase",
    "department":"Testers",
    "job_title":"Head of Testing",
    "administrator":true
    "created_at":1307751479,
    "address":null,
    "home_phone":null,
    "mobile_phone":null,
    "skype":null,
    "timezone":"London",
    "week_start":0,
    "work_phone":null
}

Avatars

To upload an avatar you need to submit as multipart and send the file data in the avatar parameter.

A persons avatar is always available at:

https://acme.minutebase.com/people/:person_id/avatar/:size

Where :size can currently be one of:

• large - 164px x 164px
• normal - 64px x 64px
• small - 32px x 32px
• tiny - 20px x 20px

If an avatar is not set for them the default avatar will be returned, so this URL is guaranteed to return an image.

Update Person

PUT https://acme.minutebase.com/api/v1/people/:person_id

Input

Send the fields you wish to change as a JSON document.

{
    "email":"bob.tester@example.com"
}

Response

{
    "id":"4df2b437cf02a319a90009ea",
    "user_id":null,
    "firstname":"Bob",
    "surname":"Tester",
    "email":"bob.tester@example.com",
    "company":"MinuteBase",
    "department":"Testers",
    "job_title":"Head of Testing",
    "administrator":true
    "created_at":1307751479,
    "address":null,
    "home_phone":null,
    "mobile_phone":null,
    "skype":null,
    "timezone":"London",
    "week_start":0,
    "work_phone":null
}

Remove Person

DELETE https://acme.minutebase.com/api/v1/people/:person_id

Response

204 HTTP status with an empty body

Get one time login key

Useful for integrating MinuteBase into your intranet where you've already authenticated the user and don't want them to have to login again.

GET https://acme.minutebase.com/api/v1/people/:person_id/otk

Response

{"otk":"123456abcdef"}

You can then use the one-time-key to redirect the person to your MinuteBase account with the otk in the query-string where they will be automatically logged in:

http://acme.minutebase.com?otk=123456abcdef

The key is valid for one use only (which is why we call it a "one time key") and only for 60 seconds after it is generated.

If the API key belongs to an account administrator you can generate a key for any person in the account. Otherwise you can only generate a key for the person the API key belongs to.

For obvious reasons, this is disabled by default (403 errors will be returned if it's not enabled).
Contact us if you need this functionality enabling for your account.

Returns 404 if you try and generate a key for a non-user (person without a login).