Resources

In the Planbox API a user is called a resource. There are two ways to retrieve resources in Planbox. Function get_resourcesgets users involed on a particular product. Objects returned contain context information (i.e. projects, roles and associations). Function get_contacts gets all users in your Planbox network. That is, anyone you are on a product with.

A resource can be added to a product through invitation. In addition, Planbox offers you granularity for inviting resources to projects. For example, given product ACME with projects ABC and DEF, you can invite a resource to only project ABC. That resource will be on product ACME, but will only see stories in project ABC. Use the invite_resource and remove_resource API calls.

In Planbox a user can be assigned a role. You can turn this feature on per initiative as described here. Use the API calls get_roles and change_roles to modify those.


https://work.planbox.com/api/get_logged_resource

Retrieves the logged resource object.

POST Arguments

None

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is the logged resource object on success or an error message string upon failure.

The logged resource object has these properties:

  • id: Unique resource id
  • name: Full name of the resource.
  • email: Email of the resource.
  • image: Image URL to the resource's avatar.
  • newsletter: 1 if the resource receives the newsletter, 0 if not.
  • https: 1 if the resource has turned on HTTPS access to Planbox, 0 if not.
    Note: This only affects the UI. HTTPS is always available for API calls.
  • package_id: Type of Planbox account.
  • package_expires_on: Date when the account expires.
  • user_limit: Maximum number of people which can be invited for this account (on initiatives owned by the logged resource).
  • user_count: Number of people invited on this account.
  • activity: Number of activities performed in Planbox in the past 7 days.

Javascript Example

Uses jQuery's post function to fetch resources involved on product id 1234.

$.post('https://work.planbox.com/api/get_logged_resource', 'json');

https://work.planbox.com/api/get_resources

Retrieves all resources involved on a product.

POST Arguments

  • product_id: Product from which to retrieve resources.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an array of resource objects on success or an error message string upon failure.

A resource object has these properties:

  • id: Unique resource id
  • name: Full name of the resource.
  • email: Email of the resource.
  • image: Image URL to the resource's avatar.
  • first_login: Date and time of first login in Planbox.
  • is_owner: Boolean. true if the resource is the product owner, false if not.
  • permission: Resource permission on the product. Can be one of: read, write or admin. See Planbox Permissions for more information.
  • role_ids: Array of role ids on this product.
  • project_ids: Array of project ids in this product. Note: The list is curated based on the logged resource permission.
  • project_associations: Object map of associations this resource has on each project. See Projects & Teams for more information.
  • project_roles: Object map of roles this resource has on each project.
  • capacity: Available work hours for this resource on this product.
  • activity: Number of activities performed in Planbox on this product in the past 7 days.

Javascript Example

Uses jQuery's post function to fetch resources involved on product id 1234.

$.post('https://work.planbox.com/api/get_resources', {product_id:1234}, 'json');

https://work.planbox.com/api/get_contacts

Retrieves all resources involved on any product the logged user is on.

POST Arguments

None

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an array of resource objects on success or an error message string upon failure.

A resource object has these properties:

  • id: Unique identifier.
  • resource_id: Unique resource id.
  • name: Full name of the resource.
  • email: Email of the resource.
  • image: Image URL to the resource's avatar.
  • activity: Number of activities performed in Planbox in the past 7 days.

Javascript Example

Uses jQuery's post function to fetch contacts.

$.post('https://work.planbox.com/api/get_contacts', 'json');

https://work.planbox.com/api/invite_resource

Invites or adds a resource to all projects or a specifc project in a Planbox product. The resource is identified by his/her email address. If the resource is new to Planbox, a Free account is automatically created. If the resource is new to the initiative, an email will be sent with instructions on how to login and access. You can suppress the sending of email by setting do_not_send_email to 1.

Note: The resource making this call must have admin privileges on the product to make this call.

POST Arguments

  • product_id: Product to invite on.
  • project_id: Optional. Project to invite on. If omitted, the resource will be invited to all projects in the product.
  • association: Optional. Type of association on the project(s). Either worker or observer. If observer and the resource is new to the product, his/her permission will be set to read.
  • roles: Optional. An array of role objects. See change_roles for details. Leave this blank if association is observer or theRoles feature is turned off on your product. If you omit, Planbox will give you a default role of Member (mbr).
  • email: Resource email. For an existing resource, must be the email he/she uses to login.
  • name: First and last name of the resource.
  • do_not_send_email: Optional. Default is 0. Set to 1 to prevent Planbox from sending an email to the resource.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an array of objects on success or an error message string upon failure.

The result object contains arrays of resource, product and project objects.

Javascript Example

Uses jQuery's post function to invite John Doe on product 1234 as an observer.

$.post('https://work.planbox.com/api/invite_resource', {
product_id: 1234,
email: "john@doe.com",
name: "John Doe"
}, 'json');

https://work.planbox.com/api/remove_resource

Removes a resource from a product or some of its projects. To remove a resource from all projects, omit the project_ids argument.

Note 1: When a resource is removed from a project, any task he/she had assigned will become unassigned. This only affects items in Current, Backlog or future iterations.

Note 2: The user making this call must have admin privileges on the product to make this call.

POST Arguments

  • product_id: Product.
  • resource_id: The resource to remove.
  • project_ids[]: Optional. List of project ids to remove the resource from. If omitted, the resource is removed from the entire product and all of its projects.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an array of objects on success or an error message string upon failure.

The result object contains arrays of updated product and project objects.

Javascript Example

Uses jQuery's post function to remove resource 1212 from all projects on product 1234.

$.post('https://work.planbox.com/api/remove_resource', {
product_id: 1234,
resource_id: 1212
}, 'json');

https://work.planbox.com/api/change_roles

Changes the roles of a resource on a project. Will create new roles on the fly if they don't exist.

Note: The user making this call must have admin privileges on the product to make this call.

POST Arguments

  • product_id: Product.
  • project_id: Project.
  • resource_id: Resource.
  • roles: An array of role objects. Each role object must be in this form.
  •  - id: Optional. Role id. Omit if you are adding a new role.
  •  - alias: Optional. Role alias. Up to 3 characters. You can omit if role id is specified.
  •  - name: Role name. You can omit if role id is specified.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an array of objects on success or an error message string upon failure.

The result object contains arrays of resource, product and project objects.

Javascript Example

Uses jQuery's post function to change the resource's roles on the specific project to Developer (dev), Member (mbr) and Marketing (mkt).

$.post('/api/change_roles', {
    product_id: 1234,
    project_id: 5678,
    resource_id: 1212,
    roles: [
        {id:3},
        {alias:'mbr', name:'Member'},
        {alias:'mkt', name:'Marketing'}
]
}, 'json');

https://work.planbox.com/api/get_roles

Retrieves the roles given to resources on a given product. The list of roles returned is curated based on the projects visible to the logged user.

POST Arguments

  • product_id: Product.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> is an array of roles on success or an error message string upon failure.

Each role object has these attributes.

  • id: Unique role id.
  • alias: Role alias. Up to 3 characters.
  • name: Role name.
  • resource_ids: Resource ids which have this role on the product.

Javascript Example

Uses jQuery's post function to fetch roles on product id 1234.

$.post('https://work.planbox.com/api/get_roles', {product_id: 1234}, 'json');


NOTE: We are in the midst of publishing our API. More to come soon... Email us at help@planbox.com to help us prioritize.

Feedback and Knowledge Base