Sign Up | Login


30 Boxes API

The 30 Boxes API is open for non-commercial application development. The API has been stable for some time, but we still change, update, and add methods as we recieve your feedback!
  • The 30 Boxes API supports the REST format. Examples requests and responses can be found for each method we support. If you need a method that we don't have, ask for it in the API forum and we'll consider it.
  • The general format of requests is an HTTP GET or POST that looks like:
    http://30boxes.com/api/api.php?method={method}&apiKey={your API key}&arg1={argument 1}...
  • To get started, you need to get your API key.
  • Most methods require you to obtain an Authorized User Token. See the user.Authorize method for details. Users will be able to see when your application accesses their data.
  • All dates and times are in the user's time zone with no alterations.
  • Boolean values are represented as 1 or 0.

Check out the API forum for more help, bug reports, questions, etc.

Methods:
test.Ping
user.FindByEmail
user.FindById
user.FindByFacebookId
user.Authorize
user.GetAllInfo
user.SetStatus
events.Get
events.GetDisplayList
events.GetById
events.GetRecentUpdates
events.GetRecentDeletions
events.Search
events.SearchByExternalUID
events.GetTags
events.TagSearch
events.Delete
events.AddByOneBox
events.AddByElements
events.Update
todos.Get
invitation.SetResponse
invitation.Delete
todos.Add
todos.Update
todos.Delete

WARNING: you are not logged in. The example links will not work properly!
Method Details Note the examples use YOUR API key, which you should not share or post online.

test.Ping
Required arguments:
apiKey
Optional arguments:
none
Example:

user.FindByEmail
Required arguments:
apiKey
email - the email address of the user you want to find
Optional arguments:
none
More Info:
If a user if found, the known PUBLIC information will be returned. To access private information, such as contact info, you need to use the method user.GetAllInfo, which requires Authorization
Example:

user.FindById
Required arguments:
apiKey
id - the id of the user you want to find
Optional arguments:
none
More Info:
If a user if found, the known PUBLIC information will be returned. To access private information, such as contact info, you need to use the method user.GetAllInfo, which requires Authorization
Example:

user.FindByFacebookId
Required arguments:
apiKey
id - the Facebook id of the user you want to find
Optional arguments:
none
More Info:
If a user if found, the known PUBLIC information will be returned. To access private information, such as contact info, you need to use the method user.GetAllInfo, which requires Authorization
Example:

user.Authorize
Required arguments:
apiKey
applicationName - the name of your application, up to 150 characters
applicationLogoUrl - the url-encoded location of your logo
Optional arguments:
returnUrl - the url-encoded location where we will return to with a user token. All web-based applications should provide a URL. If it is not provided (which would be the case for client applications), we will instruct the user to copy the token to your application
More Info:
Unlike all other methods that return XML, this URL presents the user with a message asking them if they want to give you permission for your application to access their data. They may be required to log in first. If they choose to give permission, we will provide (through the returnUrl, or a form in your application) an authorizedUserToken that you need when accessing their data. This token will not expire for a given user, so you may wish to store it.

Note that you cannot authorize a specific user; you are getting authorization to access whomever logs in. Upon success, we tell you their identification.
Example:

user.GetAllInfo
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
none
More Info:
This method returns private contact info and a list of the user's buddies.
Example:

user.SetStatus
Required arguments:
apiKey
authorizedUserToken
status - the new status for the user (can be empty)
Optional arguments:
none
More Info:
This method sets a user's status. The current user's status can be obtained from user.GetAllInfo().
Example:

events.Get
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
start - return events starting on or after this date. Defaults to today.
end - return events starting on or before this date. Defaults to start + 90 days. Cannot be more then 180 days after start.
More Info:
Note that events are not returned in any particular order. If the event is an invitation, additional data is included (see example). Events that are invitations cannot be edited. For repeating events, both a "simplified" version of the pattern is supplied (which may omit some details, but is easy to parse), as well as a "repeatICal" format, which includes all details but is harder to parse.
Example:

events.GetDisplayList
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
start - return events starting on or after this date. Defaults to today.
end - return events starting on or before this date. Defaults to start + 30 days. Cannot be more then 180 days after start.
More Info:
Note that events repeating events are expanded and all events are sorted (unlike events.Get). As a result, events in the list will have the same ID but different start/end dates. Do NOT edit event data obtained from this function (use events.Get or events.GetById)! If the event is an invitation, additional data is included (see example). Events that are invitations cannot be edited.
Example:

events.GetById
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
eventId - The Id of the event to get. The event must be owned by this user.
More Info:
This method returns a single event, which could be useful if you tie 30 Boxes events to something else.
Example:

events.GetRecentUpdates
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
since - return events that have been created or updated on or after this date. Defaults to 60 days ago.
More Info:
Note that events are not returned in any particular order. If the event is an invitation, additional data is included (see example). Events that are invitations cannot be edited.
Example:

events.GetRecentDeletions
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
since - return events that have been deleted on or after this date. Defaults to 60 days ago.
More Info:
This returns events that were owned by the authorized user AND events that this user was invited to (but owned and deleted by someone else).
Example:

events.Search
Required arguments:
apiKey
authorizedUserToken
query - the word(s) you want to search
Optional arguments:
none
More Info:
This method will search event summaries, notes, and tags. Unlike the web site, the API only searches this user's events, and not those owned by buddies.
Example:

events.SearchByExternalUID
Required arguments:
apiKey
authorizedUserToken
externalUID - the externalUID you want to search
Optional arguments:
none
More Info:
This method will return all the user's events that match the given external UID.
Example:

events.GetTags
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
none
More Info:
This method will return all tags used in events.
Example:

events.TagSearch
Required arguments:
apiKey
authorizedUserToken
tag - the tag you want to search
Optional arguments:
none
More Info:
This method will search returns events that that contain the given tag.
Example:

events.Delete
Required arguments:
apiKey
authorizedUserToken
eventId - the ID of the event to delete
Optional arguments:
none
More Info:
This method will delete a given event. The authorized user must be the owner of the event.
Example:

events.AddByOneBox
Required arguments:
apiKey
authorizedUserToken
event - the text entry of the event, e.g. "meeting with Bob tomorrow 3pm (bring laptop)"
Optional arguments:
none
More Info:
This method will create a new event using the same text parsing as the One Box on the 30 Boxes website. Note that clicking the example URL will create an event in your calendar!
Example:

events.AddByElements
Required arguments:
apiKey
authorizedUserToken
summary - summary of the event, e.g. "meeting with Bob"
Optional arguments:
notes - notes of the event, e.g. "bring laptop"
dateStart - start date, e.g. "may 5 2006"
timeStart - start time, blank if all-day event, e.g. "5pm"
dateEnd - end date, blank if same as start, e.g. "5/15/2006"
timeEnd - end time, blank if all day event or no end time, e.g. "5:00pm"
tags - tags, separated by a space, e.g. "work meetings"
invites - email addresses to invite, separated by spaces and preceeded by "+", e.g. "+tom@acme.com +jill@acme.com"
privacy - allowed values are "shared" or "private"
externalUID - up to 100 chars allowed for external application's use, such as the event ID in the external application
repeat - allowed values are "no","weekly","biweekly","monthly","yearly"
repeatEnd - last occurence of a repeating event (blank if no end date), e.g. june 5 2006
skipDates - dates to skip for repeating events, separated by a space, e.g. "5/14/2006 5/21/2006"
repeatICal - an iCal-formatted repeat pattern (escaped to be a valide cgi value), e.g. "RRULE%3AFREQ%3DMONTHLY%3BINTERVAL%3D2%3B". If present, it will override other repeat settings.
reminder - time, in seconds, before event to send reminder, -1 means no reminder. Allowed values are 300 (5 minutes), 1800, 3600, 7200, 14400, 43200, 86400 (one day), 172800, 604800 (one week), 1209600, 2419200 (4 weeks). Using other values could cause the reminder to fail.
More Info:
This method will create a new event from individual form elements, similar to the advanced entry form on the 30 Boxes website. Note that clicking the example URL will create an event in your calendar!
We recommend you use an HTTP POST instead of GET with this method.
Example:

events.Update
Required arguments:
apiKey
authorizedUserToken
eventId - id of event, e.g. 12345
summary - summary of the event, e.g. "meeting with Bob"
Optional arguments:
notes - notes of the event, e.g. "bring laptop"
dateStart - start date, e.g. "may 5 2006"
timeStart - start time, blank if all-day event, e.g. "5pm"
dateEnd - end date, blank if same as start, e.g. "5/15/2006"
timeEnd - end time, blank if all day event or no end time, e.g. "5:00pm"
tags - tags, separated by a space, e.g. "work meetings"
invites - email addresses to invite, separated by spaces and preceeded by "+", e.g. "+tom@acme.com +jill@acme.com"
privacy - allowed values are "shared" or "private"
externalUID - up to 100 chars allowed for external application's use, such as the event ID in the external application
repeat - allowed values are "no","weekly","biweekly","monthly","yearly"
repeatEnd - last occurence of a repeating event (blank if no end date), e.g. june 5 2006
skipDates - dates to skip for repeating events, separated by a space, e.g. "5/14/2006 5/21/2006"
repeatICal - an iCal-formatted repeat pattern (escaped to be a valide cgi value), e.g. "RRULE%3AFREQ%3DWEEKLY%3BINTERVAL%3D2%3B". If present, it will override other repeat settings.
reminder - time, in seconds, before event to send reminder, -1 means no reminder. Allowed values are 300 (5 minutes), 1800, 3600, 7200, 14400, 43200, 86400 (one day), 172800, 604800 (one week), 1209600, 2419200 (4 weeks). Using other values could cause the reminder to fail.
More Info:
This method updates an existing event.
We recommend you use an HTTP POST instead of GET with this method.
Example:

todos.Get
Required arguments:
apiKey
authorizedUserToken
Optional arguments:
none
More Info:
Returns to do items in the order the user has set.
Example:

invitation.SetResponse
Required arguments:
apiKey
authorizedUserToken
eventId - id of event, e.g. 12345
response - either 'yes', 'no', or 'unknown'
Optional arguments:
none
More Info:
Sets the response to an invited event (in the event record, the <isInvitation> field will be set to 1).
Example:

invitation.Delete
Required arguments:
apiKey
authorizedUserToken
eventId - id of event, e.g. 12345
Optional arguments:
none
More Info:
Deletes this invitation to an event (in the event record, the <isInvitation> field will be set to 1).
Example:

todos.Add
Required arguments:
apiKey
authorizedUserToken
text - text of the to do item, e.g. "Buy milk"
Optional arguments:
tags - tags, separated by a space, e.g. "grocery home"
done - item is completed (0 or 1)
externalUID - up to 100 chars allowed for external application's use, such as the event ID in the external application
More Info:
This method will add a new to do item.
Example:

todos.Update
Required arguments:
apiKey
authorizedUserToken
todoId - the ID of the to do item to delete
Optional arguments:
text - text of the to do item, e.g. "Buy milk"
tags - tags, separated by a space, e.g. "grocery home"
done - item is completed (0 or 1)
externalUID - up to 100 chars allowed for external application's use, such as the event ID in the external application
More Info:
This method will update to do item, which must be owned by the authorized user.
Example:

todos.Delete
Required arguments:
apiKey
authorizedUserToken
todoId - the ID of the to do item to delete
Optional arguments:
none
More Info:
This method will delete a given to do item. The authorized user must be the owner of the item.
Example:


Questions, comments, suggestions? Check out the Developer Forum

 

loading... hang on just one sec...