hang on just one sec...
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!
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 |
| 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.
Example:
Note that you cannot authorize a specific user; you are getting authorization to access whomever logs in. Upon success, we tell you their identification. |
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!
Example:
We recommend you use an HTTP POST instead of GET with this method. |
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.
Example:
We recommend you use an HTTP POST instead of GET with this method. |
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 |
hang on just one sec...