FeatureMap REST API v1.0

Endpoints

• GET maps

  Get the descriptions of all the current user's maps.

  This endpoint provides the list of all the current user's maps along with some useful info for each map. It does not provide the full content of each map (such as the cards list).

  Use the endpoint below to get the content of a specific map.

  Responses

  Status 200 - OK

  An array of MapDescriptions representing the current user's maps.

• GET maps/{ownerName}/{cleanName}?expand

  Get the content of the specified map.

  This endpoint can provide the full content of the specified map. Each map is identified by its owner name and by its clean name.

  Arguments

  • ownerName (string) :
    The map's owner name.
  • cleanName (string) :
    The map's clean name.
  • expand (string, optional, default: "cards,participants") :
    Indicates the attached resources to be returned with the map.

    This argument can be used to indicate which properties of the returned map resource should be expanded. In other words, it can be used to indicate which map sub-resources you want to fetch along with the map. For example it can indicate whether or not you want to retrieve the map's set of cards inside the returned Map object (i.e. expand its cards property).

    The following properties are expandable:

    • participants: the map's participants.
    • pendingInvitations: the current pending invitations.
    • cards: the cards of the map.
    • customProperties: the map's custom properties.

    In addition, the following properties of the map's cards can be expanded:

    • cards.comments: for each card, expand the list of its comments (see Card.comments).
    • cards.attachments: for each card, expand the list of its attachments (see Card.attachments).
    • cards.checklist: for each card, expand its attached checklist (see Card.checklist).
    • cards.subscribers: for each card, expand the list of its subscriber names (see Card.subscriberNames).
    • cards.customProperties: for each card, attach its custom properties (see Card.customProperties).

    The name of the properties to expand must be separated with a comma (','). For example, "cards,participants" indicates that you want to fetch the list of cards and the list of participants of the map. You can also use "all" to indicate that you want to expand all the map properties, and/or "cards.all" to indicate you want to fetch all of the attached resources of each card of the map.

  Responses

  Status 200 - OK

  The requested Map.

• POST maps

  Create a new map.

  This endpoint can be used to create a map. There are 3 modes available:

  • "Empty" to create a new map from scratch;
  • "Copy" to copy an existing map;
  • "Data" to create a new map from the data that you provide.

  This endpoint expects a javascript object as request body describing the mode to use and the corresponding options.

  For the mode "Empty", the following options are available:

  • mapName: The name of the map to create.
  • noCards: Use "true" (as a string) to create a new map with no cards.

  Example of request: { "mode": "Empty", "options": { "mapName": "My new map", "noCards": "false" } }

  For the mode "Copy", the following options are available:

  • mapName: The name of the map to create.
  • referenceMapOwnerName: The owner name of the map to copy.
  • referenceMapCleanName: The clean name of the map to copy.

  Example of request: { "mode": "Copy", "options": { "mapName": "Foo - Copy", "referenceMapOwnerName": "myusername", "referenceMapCleanName": "foo" } }

  The mode "Data" has no options. Use the property "data" to define the map content in the form of a Map object.

  Example of request: { "mode": "Data", "data": { "name": "Foo", "cards": [ {"id": 1, "role": "GroupHeader", "title": "My group"}, {"id": 2, "role": "ListHeader", "title": "My list", "parentCardId": 1} ] } }

  The response body will be a javascript object with a property status indicating the result of the operation. The possible values for this property are the following:

  • "Success": the map was successfully created.
  • "InvalidRequest": the request was invalid. See the message property for details.
  • "LicenceUpgradeRequired": the current user has reached the map quota defined by his current subscription.

  Expected request body

  An object with the following properties:

  • mode (string): must be either "Empty" or "Copy".
  • options (object): an object specifying some options for the map creation, such as the map name.

  Responses

  Status 201 - Created

  An object with the following properties:

  • status (string): the result of the operation.
  • message (string): a message describing the result.
  • mapOwnerName (string): the owner name of the created map (if the operation succeeded).
  • mapCleanName (string): the clean name of the created map (if the operation succeeded).
  • mapUniqueId (string): the unique ID of the created map (if the operation succeeded).

• PUT maps/{ownerName}/{cleanName}

  Update the properties of the specified map.

  This endpoint can be used to update one or several of the following Map properties:

  • name
  • groupsLabel
  • listsLabel
  • layersLabel

  Any undefined property in the request body will be considered as having a null value. Therefore you should always specify the value of all updatable properties (even those you don't want to change) when using this endpoint.

  Arguments

  • ownerName (string) :
    The map's owner name.
  • cleanName (string) :
    The map's clean name.

  Expected request body

  A Map with all updatable properties defined.

  Responses

  Status 200 - OK

  The updated Map without its sub-resources (cards, participants etc).

• DELETE maps/{ownerName}/{cleanName}

  Leave or delete the specified map.

  If the specified map has several active (non Revoked) participants, this action will simply remove this map from the list of maps of the current user and revoke his access to it.

  If the current user is the only active participant, this action will delete the map and all its content permanently.

  Arguments

  • ownerName (string) :
    The map's owner name.
  • cleanName (string) :
    The map's clean name.

  Responses

  Status 204 - NoContent

  Returned when the map was left or deleted.

• GET maps/{mapOwnerName}/{mapCleanName}/participants

  Get the list of the specified map's participants.

  This is the unordered list of participants in the map.
  Any user who once had access to this map is considered a participant of the map.

  Note that this list might contain users who no longer have access to this map. In that case the value of their MapParticipant.participantRole property will be "Revoked".

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.

  Responses

  Status 200 - OK

  An array of MapParticipants representing the map's participants.

• GET maps/{mapOwnerName}/{mapCleanName}/invitations

  Get the map's pending invitations.

  An invitation is created and marked as pending each time a Map administrator invites a new participant using an email address which does not correspond to an already registered user of the application. When the invited user signs up using this email address, this user automatically becomes a map participant (with the access right specified by the invitation) and the invitation is discarded.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.

  Responses

  Status 200 - OK

  An array of MapInvitations representing the map's pending invitations.

• POST maps/{mapOwnerName}/{mapCleanName}/invitations

  Invite a user to access the specified map.

  This endpoint can be used to share a map with a given user, identified by his email address.

  If there is no registered user with the given address, a MapInvitation is created and it is returned through the invitation property of the response body.

  If there is a registered user with that addresss, a MapParticipant is created (or an existing MapParticipant is restored) and it is returned through the participant property of the response body.

  The result property of the response body indicates the result of the operation. The possible values are:

  • "GrantedAccess": The invited user had already signed up and has now access to the map. A new MapParticipant was added.
  • "RestoredAccess": The existing MapParticipant was updated and its role is no longer "Revoked".
  • "GrantedSuspendedAccess": A new MapParticipant was created but the user's subscription does not allow him to access any more maps. His access is thus suspended.
  • "RestoredSuspendedAccess": The participant's role is no longer Revoked but the user's subscription does not allow him to access any more maps. His access is thus suspended.
  • "SentInvitation": There is no registered user with that email address. An email was sent and a new MapInvitation was added.
  • "ForbiddenEmailDomain": Sending invitations to this particular email domain is not allowed.
  • "UserHasAlreadyAccess": The specified user already has access to this map.
  • "UserWasAlreadyInvited": There already is a pending invitation for this user.
  • "InvalidArguments": The email address is invalid or the participant role is Revoked.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.

  Expected request body

  A MapInvitation. The message property can be null.

  Responses

  Status 200 - OK

  An object containing the result of the operation and the corresponding MapInvitation or MapParticipant.

• PUT maps/{mapOwnerName}/{mapCleanName}/participants/{username}

  Update the role of a map participant.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • username (string) :
    The participant's username.

  Expected request body

  A MapParticipant object with its MapParticipant.participantRole property defined.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's success:

  • "UpdatedRole": The participant's role has been updated.
  • "RevokedAccess": The participant's role was changed to Revoked and the user has therefore no longer access to this map.
  • "RestoredAccess": The user's access to this map has been restored (the participant's role is no longer Revoked).
  • "RestoredSuspendedAccess": The participant's role is no longer Revoked but the user's subscription does not allow him to access any more maps. His access is thus suspended.
  • "UserIsSingleAdmin": The role could not be updated because this user is the unique Administrator of this map and at least one Administrator must remain.

• PUT maps/{mapOwnerName}/{mapCleanName}/invitations/{email}

  Update the role associated with the invitation sent to the specified email.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • email (string) :
    The email the invitation was sent to.

  Expected request body

  A MapInvitation object with its MapInvitation.participantRole property defined.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's success:

  • "UpdatedRole": The role associated with this invitation has been updated.
  • "CancelledInvitation": The invitation to this email has been cancelled.

• DELETE maps/{mapOwnerName}/{mapCleanName}/participants/{username}

  Revoke a user's access to the specified map.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • username (string) :
    The participant's username.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's result:

  • "RevokedAccess": The user's role was changed to Revoked and the user has therefore no longer access to this map.
  • "UserIsSingleAdmin": The role could not be updated because this user is the unique Administrator of this map and at least one Administrator must remain.
  • "UserHadAlreadyNoAccess": The user had already no access to this map.

• DELETE maps/{mapOwnerName}/{mapCleanName}/invitations/{email}

  Cancels an invitation to join the specified map.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • email (string) :
    The email the invitation was sent to.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's result:

  • "CancelledInvitation": The invitation has been canceled.
  • "UserHadAlreadyNoAccess": There was already no pending invitation to this email address.

• GET maps/{mapOwnerName}/{mapCleanName}/cards?expand

  Get the list of cards of the specified map.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • expand (string, optional, default: "") :
    Indicates the attached resources to be returned with each card.

    This argument can be used to indicate which properties of the returned cards resources should be expanded. In other words, it can be used to indicate which card sub-resources you want to fetch along with the list of cards. For example it can indicate whether or not you want to retrieve each card's set of comments inside each returned Card object (i.e. expand its comments property).

    The following properties are expandable:

    • comments: for each card, expand the list of its comments (see Card.comments).
    • attachments: for each card, expand the list of its attachments (see Card.attachments).
    • checklist: for each card, expand its attached checklist (see Card.checklist).
    • subscribers: for each card, expand the list of its subscriber names (see Card.subscriberNames).
    • customProperties: for each card, attach its custom properties (see Card.customProperties).

    The name of the properties to expand must be separated with a comma (','). For example, "comments,checklist" indicates that you want to fetch the list of comments and the checklist of each card. You can also use "all" to indicate that you want to expand all the card properties.

  Responses

  Status 200 - OK

  An array of Cards representing the set of cards of the specified map.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}?expand

  Get the specified card.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • expand (string, optional, default: "") :
    Indicates the attached resources to be returned with the card.

    This argument can be used to indicate which properties of the returned card resources should be expanded. In other words, it can be used to indicate which card sub-resources you want to fetch along with the specified cards. For example it can indicate whether or not you want to retrieve the card's set of comments inside the returned Card object (i.e. expand its comments property).

    The following properties are expandable:

    • comments: expand the list of comments of this card (see Card.comments).
    • attachments: expand the list of attachments of this card (see Card.attachments).
    • checklist: expand the attached checklist of this card (see Card.checklist).
    • subscribers: expand the list of subscriber names of this card (see Card.subscriberNames).
    • customProperties: attach the custom properties of this card (see Card.customProperties).

    The name of the properties to expand must be separated with a comma (','). For example, "comments,checklist" indicates that you want to fetch the list of comments and the checklist of the card. You can also use "all" to indicate that you want to expand all the card properties.

  Responses

  Status 200 - OK

  An array of Cards representing the set of cards of the specified map.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/position

  Get the position of the specified card.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Responses

  Status 200 - OK

  A CardPosition.

• POST maps/{mapOwnerName}/{mapCleanName}/cards

  Create a new card in the specified map.

  A card must be created at a valid position in the map (see CardPosition). The new card's ID and uniqueId will be assigned automatically.

  A card can be virtual, in which case it has no content and act as a placeholder for a group header, list header or layer header, otherwise it should at least have a title or a description.

  As a special case, when a new group header is created a (virtual) list header is created at the same time. The ID of the new list header will be the ID of the created group header + 1.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.

  Expected request body

  A Card with a valid position.

  Responses

  Status 201 - Created

  The created Card.

• PUT maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}

  Update the properties of the specified card.

  This endpoint can be used to update one or several of the following Card properties:

  • isVirtual
  • title
  • description
  • importance
  • estimation
  • estimationMode
  • estimationLabel
  • estimationUnit
  • budget
  • budgetMode
  • budgetLabel
  • budgetUnit
  • status
  • color
  • dueDate

  Any undefined property in the request body will be considered as having a default value. Therefore you should always specify the value of all updatable properties (even those you don't want to change) when using this endpoint.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  A Card with all updatable properties defined.

  Responses

  Status 200 - OK

  The updated Card.

• PUT maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/position

  Move the specified card.

  This endpoint can be used to update the position of a card inside a map. It cannot move a card to another map.

  Each card of a map must have a valid position at all times (see CardPosition). Therefore:

  If the new card's role is GroupHeader, LayerHeader or BenchItem, parentCardId must be null and otherParentCardId must be null.

  If the new card's role is ListHeader, parentCardId must be the ID of a card having the "GroupHeader" role and otherParentCardId must be null.

  If the new card's role is ListItem, parentCardId must be the ID of a card having the "ListHeader" role and otherParentCardId must be the ID of a card having the "LayerHeader" role.

  If the new card's index is less or equal to 0, the card will be inserted at the beginning of the cards that may be already present at the specified position.

  If the new card's index is superior or equal to the number of cards already present at the specified position, the card will be inserted at the end.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  A valid CardPosition.

  Responses

  Status 200 - OK

  The updated CardPosition of the card.

• DELETE maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}?deleteAttachedCards

  Delete the specified card.

  When a card is deleted, every comment, attachment and checklist item is also deleted.

  There is no way to recover a deleted card.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • deleteAttachedCards (boolean, optional, default: true) :
    Indicates whether the cards attached to the specified card must also be deleted.

    If this argument is true (default value), and if the specified card has other cards attached to it, then these cards will also be deleted. For example if the specified card is a list header, the cards inside that list will all be deleted.

    If this argument is false, the card will be deleted only if there is no cards attached to it. Otherwhise it will become virtual and the attached cards will remain attached to it.

  Responses

  Status 204 - NoContent

  Returned when the card was deleted.

  Status 200 - OK

  The updated (now virtual) Card.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/subscriberNames

  Get the list of subscribers of the specified card.

  The items of the returned list are usernames of active (non revoked) participants of the map.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Responses

  Status 200 - OK

  An array of usernames (strings).

• PUT maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/subscriberNames

  Update the list of subscribers of the specified card.

  This endpoint can be used to update the list of subscribers of the specified card.

  Each item in the list must be the username of an active (non revoked) participant of the map.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  An array of usernames (strings).

  Responses

  Status 200 - OK

  The updated list of usernames.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/comments

  Get the list of comments of the specified card.

  The returned list is ordered from newest to oldest comment.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Responses

  Status 200 - OK

  An array of Comments representing the list of comments attached to the specified card.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/comments/{commentId}

  Get the specified comment.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • commentId (integer) :
    The comment ID.

  Responses

  Status 200 - OK

  The requested Comment.

• POST maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/comments

  Add a new comment to the specified card.

  The new comment's ID will be assigned automatically.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  A Comment object with its message property defined.

  Responses

  Status 201 - Created

  The new Comment.

• PUT maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/comments/{commentId}

  Update the message of the specified comment.

  This endpoint can be used to update the message property of the specified comment.

  A comment can only be updated by its original author.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • commentId (integer) :
    The comment ID.

  Expected request body

  A Comment object with its message property defined.

  Responses

  Status 200 - OK

  The updated Comment.

• DELETE maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/comments/{commentId}

  Delete the specified comment.

  A comment can only be deleted by its original author.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • commentId (integer) :
    The comment ID.

  Responses

  Status 204 - NoContent

  Returned when the comment was deleted.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/attachments

  Get the list of attachments (links, files) of the specified card.

  The returned list is ordered from newest to oldest attachment.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Responses

  Status 200 - OK

  An array of Attachments representing the list of attachments of the specified card.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/attachments/{attachmentId}

  Get the specified card attachment.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • attachmentId (integer) :
    The attachment ID.

  Responses

  Status 200 - OK

  The requested Attachment.

• POST maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/attachments/link

  Add an hyperlink as attachment to the specified card.

  The new attachment's ID will be assigned automatically.
  The type of the new attachment will be "Link".

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  An Attachment object with its name and linkUrl properties defined.

  Responses

  Status 201 - Created

  The new Attachment.

• POST maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/attachments/file

  Upload a file and add it as attachment to the specified card.

  This endpoint accepts a request of type "multipart/form-data".

  The name defined as Content-Disposition must be "file". The filename must indicate the name of the file you are uploading.

  The new attachment's ID will be assigned automatically.
  The type of the new attachment will be "File".

  Example of request:

  POST https://www.featuremap.co/api/1/maps/johndoe/foo/cards/7/attachments/file HTTP/1.1
  Accept: application/json, text/javascript
  Content-Type: multipart/form-data; boundary=---------------------------7dfea844066c
  Content-Length: {file size}

  -----------------------------7dfea844066c
  Content-Disposition: form-data; name="file"; filename="{file name with extension}"
  Content-Type: {file MIME type}

  {file content}

  -----------------------------7dfea844066c--

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  A form data with the binary content of the file.

  Responses

  Status 200 - OK

  The new Attachment.

• DELETE maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/attachments/{attachmentId}

  Remove the specified card attachment.

  If the attachment is of type "File", the uploaded file will also be deleted.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • attachmentId (integer) :
    The attachment ID.

  Responses

  Status 204 - NoContent

  Returned when the attachment was removed.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/checklist

  Get the checklist of the specified card.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Responses

  Status 200 - OK

  An array of CheckListItems representing the checklist of the card.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/checklist/{itemId}

  Get the specified item of a card's checklist.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • itemId (integer) :
    The item ID.

  Responses

  Status 200 - OK

  The requested CheckListItem.

• POST maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/checklist

  Add a new item to the specified card's checklist.

  Items can be inserted anywhere in the list. The indexes of the other items might be updated accordingly.

  When creating an item you can define arbitrary custom properties by setting the value of its customProperties property with a javascript object.

  The new item's ID will be assigned automatically.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.

  Expected request body

  A CheckListItem object with its content, index and isDone properties defined.

  Responses

  Status 201 - Created

  The new CheckListItem.

• PUT maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/checklist/{itemId}?updateCustomProperties

  Updates or moves the specified checklist item.

  This endpoint can be used to update one or several of the following CheckListItem properties:

  • content
  • index
  • isDone
  • key (if updateCustomProperties is true)
  • customProperties (if updateCustomProperties is true)

  Any undefined property in the request body will be considered as having a default value. For example, { isDone: true } will be handled as { content: null, id: 0, idDone: true }. Therefore you should always specify the value of all updatable properties (even those you don't want to change) when using this endpoint.

  As an exception, custom properties will only be updated if the updateCustomProperties argument is true. In that case the customProperties and key properties should be defined as well in the request body.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • itemId (integer) :
    The item ID.
  • updateCustomProperties (boolean, optional, default: false) :
    Indicates whether the item's custom properties should be updated too.

  Expected request body

  A CheckListItem object with its updatable properties defined.

  Responses

  Status 200 - OK

  The updated CheckListItem.

• DELETE maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/checklist/{itemId}

  Remove the specified item from the card's checklist.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • cardId (integer) :
    The card ID.
  • itemId (integer) :
    The item ID.

  Responses

  Status 204 - NoContent

  Returned wen the item was removed.

• GET maps/{mapOwnerName}/{mapCleanName}/log?pageSize&pageIndex

  Get the activity log entries of the specified map.

  Entries are ordered with the most recent entries first. By default, this returns the latest 25 entries of the log.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • pageSize (integer, optional, default: 25) :
    The size of each entries "page".
  • pageIndex (integer, optional, default: 0) :
    The index of the "page" to load.

    For example if you specify pageSize=10&pageIndex=0 as query string, you will receive entries 0 to 9 (i.e. the 10 most recent entries). If you specify pageSize=20&pageIndex=2, you will receive entries 40 to 59.

  Responses

  Status 200 - OK

  An array of ActivityLogEntries representing the requested log entries.

• GET maps/{mapOwnerName}/{mapCleanName}/cards/{cardId}/log?pageSize&pageIndex

  Get the activity log entries of the specified card.

  Entries are ordered with the most recent entries first. By default, this returns the latest 25 entries of the log.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.
  • pageSize (integer, optional, default: 25) :
    The size of each entries "page".
  • pageIndex (integer, optional, default: 0) :
    The index of the "page" to load.

    For example if you specify pageSize=10&pageIndex=0 as query string, you will receive entries 0 to 9 (i.e. the 10 most recent entries). If you specify pageSize=20&pageIndex=2, you will receive entries 40 to 59.

  • cardId (integer) :
    The card ID.

  Responses

  Status 200 - OK

  An array of ActivityLogEntries representing the requested log entries.

• GET me

  Get information about the current user.

  Responses

  Status 200 - OK

  A User object containing info about the current user.

• PUT me

  Update the current user information.

  This endpoint can be used to update one or several of the following User properties:

  • email
  • firstName
  • lastName
  • company
  • role
  • preferredCulture
  • timeZone
  • notificationEmailFrequency

  Any undefined property in the request body will be considered as having a default value. Therefore you should always specify the value of all updatable properties (even those you don't want to change) when using this endpoint.

  Expected request body

  A User object with its updatable properties defined.

  Responses

  Status 200 - OK

  The updated User object.

• GET groups

  Get the list the current user's groups.

  This endpoint provides the list of all the current user's groups.

  Responses

  Status 200 - OK

  An array of Groups representing the current user's groups.

• GET groups/{ownerName}/{cleanName}

  Get the specified group.

  This endpoint can provide the full content of the specified group. Each group is identified by its owner name and by its clean name.

  Arguments

  • ownerName (string) :
    The group's owner name.
  • cleanName (string) :
    The group's clean name.

  Responses

  Status 200 - OK

  The requested Group.

• POST groups

  Create a new group.

  The user creating the group will be considered "owner" of this group and will have the Administrator role by default.

  Expected request body

  An object with the following properties:

  • name (string): the name of the group to create.

  Responses

  Status 201 - Created

  The created Group.

• PUT groups/{ownerName}/{cleanName}

  Update the properties of the specified group.

  This endpoint can be used to update one or several of the following Group properties:

  • name
  • treasurerName

  Any undefined property in the request body will be considered as having a null value. Therefore you should always specify the value of all updatable properties (even those you don't want to change) when using this endpoint.

  Arguments

  • ownerName (string) :
    The group's owner name.
  • cleanName (string) :
    The group's clean name.

  Expected request body

  A Group with all updatable properties defined.

  Responses

  Status 200 - OK

  The updated Group.

• DELETE groups/{ownerName}/{cleanName}

  Leave or delete the specified group.

  If the specified group has several active (non Revoked) participants, this action will simply remove the current user from the members of the group.

  If the current user is the only active participant, this action will delete the group permanently.

  Arguments

  • ownerName (string) :
    The group's owner name.
  • cleanName (string) :
    The group's clean name.

  Responses

  Status 204 - NoContent

  Returned when the group was left or deleted.

• GET groups/{groupOwnerName}/{groupCleanName}/participants

  Get the list of the specified group's participants.

  This is the unordered list of participants in the group.
  Any user who was once a member of this group is considered a participant of the group.

  Note that this list might contain users who are longer part of this group. In that case the value of their GroupParticipant.participantRole property will be "Revoked".

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.

  Responses

  Status 200 - OK

  An array of GroupParticipants representing the group's participants.

• GET groups/{groupOwnerName}/{groupCleanName}/invitations

  Get the group's pending invitations.

  An invitation is created and marked as pending each time a Group administrator invites a new participant using an email address which does not correspond to an already registered user of the application. When the invited user signs up using this email address, this user automatically becomes a group participant (with the access right specified by the invitation) and the invitation is discarded.

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.

  Responses

  Status 200 - OK

  An array of GroupInvitations representing the group's pending invitations.

• POST groups/{groupOwnerName}/{groupCleanName}/invitations

  Invite a user to access the specified group.

  This endpoint can be used to invite a user into a given group, identified by his email address.

  If there is no registered user with the given address, a GroupInvitation is created and it is returned through the invitation property of the response body.

  If there is a registered user with that addresss, a GroupParticipant is created (or an existing GroupParticipant is restored) and it is returned through the participant property of the response body.

  The result property of the response body indicates the result of the operation. The possible values are:

  • "AddedMember": The invited user had already signed up and is now a member of the group. A new GroupParticipant was added.
  • "RestoredMember": The existing GroupParticipant was updated and its role is no longer "Revoked".
  • "SentInvitation": There is no registered user with that email address. An email was sent and a new GroupInvitation was added.
  • "ForbiddenEmailDomain": Sending invitations to this particular email domain is not allowed.
  • "UserIsAlreadyMember": The specified user is already a member of this group.
  • "UserWasAlreadyInvited": There already is a pending invitation for this user.
  • "InvalidArguments": The email address is invalid or the participant role is Revoked.

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.

  Expected request body

  A GroupInvitation. The message and participantRole properties are optional (default role: Member).

  Responses

  Status 200 - OK

  An object containing the result of the operation and the corresponding GroupInvitation or GroupParticipant.

• PUT groups/{groupOwnerName}/{groupCleanName}/participants/{username}

  Update the role of a group participant.

  Note that if the group's treasurer is removed (revoked) from the group, the group will no longer have a tresurer.

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.
  • username (string) :
    The participant's username.

  Expected request body

  A GroupParticipant object with its GroupParticipant.participantRole property defined.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's success:

  • "UpdatedRole": The participant's role has been updated.
  • "RevokedMember": The participant's role was changed to Revoked and the user is therefore no longer a member of this group.
  • "RestoredMember": The user is now a member of this group again (the participant's role is no longer Revoked).
  • "UserIsSingleAdmin": The role could not be updated because this user is the unique Administrator of this group and at least one Administrator must remain.

• PUT groups/{groupOwnerName}/{groupCleanName}/invitations/{email}

  Update the role associated with the invitation sent to the specified email.

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.
  • email (string) :
    The email the invitation was sent to.

  Expected request body

  A GroupInvitation object with its GroupInvitation.participantRole property defined.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's success:

  • "UpdatedRole": The role associated with this invitation has been updated.
  • "CancelledInvitation": The invitation to this email has been cancelled.

• DELETE groups/{groupOwnerName}/{groupCleanName}/participants/{username}

  Remove a user from the specified group.

  Note that if the group's treasurer is removed (revoked) from the group, the group will no longer have a tresurer.

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.
  • username (string) :
    The participant's username.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's result:

  • "RevokedMember": The user's role was changed to Revoked and the user is therefore no longer a member of this group.
  • "UserIsSingleAdmin": The role could not be updated because this user is the unique Administrator of this group and at least one Administrator must remain.
  • "UserIsAlreadyNoMember": This user was already not a member of this group.

• DELETE groups/{groupOwnerName}/{groupCleanName}/invitations/{email}

  Cancels an invitation to join the specified group.

  Arguments

  • groupOwnerName (string) :
    The group's owner name.
  • groupCleanName (string) :
    The group's clean name.
  • email (string) :
    The email the invitation was sent to.

  Responses

  Status 200 - OK

  One of these values, depending on the operation's result:

  • "CancelledInvitation": The invitation has been canceled.
  • "UserIsAlreadyNoMember": There was already no pending invitation to this email address.

• GET notifications

  Get the current user's notifications.

  Responses

  Status 200 - OK

  An array of Notifications.

• GET notifications/{notificationId}

  Get the specified notification.

  Arguments

  • notificationId (integer) :
    The notification ID.

  Responses

  Status 204 - NoContent

  No Content.

• PUT notifications/{notificationId}

  Update the specificied notification.

  This endpoint can be used to mark a notification as read or unread.

  Arguments

  • notificationId (integer) :
    The notification ID.

  Expected request body

  A Notification with its isRead property defined.

  Responses

  Status 200 - OK

  The updated Notification.

• GET webhooks

  Get the list of webhooks created by the current user.

  The returned list contains all the webhooks (active or inactive) defined by the current user, no matter their corresponding map.

  Responses

  Status 200 - OK

  An array of Webhooks representing the list of webhooks created by the current user.

• GET maps/{mapOwnerName}/{mapCleanName}/webhooks

  Get the list of webhooks defined for the specified map.

  The returned list contains all the webhooks (active or inactive) defined for the specified map. They may have been created by another user.

  Arguments

  • mapOwnerName (string) :
    The map's owner name.
  • mapCleanName (string) :
    The map's clean name.

  Responses

  Status 200 - OK

  An array of Webhooks representing the list of webhooks defined for the specified map.

• GET webhooks/{webhookId}

  Get the specified webhook.

  Arguments

  • webhookId (integer) :
    The webhook ID.

  Responses

  Status 200 - OK

  The requested Webhook.

• POST webhooks

  Create a new webhook.

  The new webhook's ID will be assigned automatically.

  Each webhook must specify an existing map and a list of event types to monitor in that map. Once the webhook is created it can't be updated to monitor another map.

  Expected request body

  A Webhook with its mapOwnerName, mapCleanName, eventTypes, callbackUrl, and isActive properties defined.

  Responses

  Status 201 - Created

  The new Webhook.

• PUT webhooks/{webhookId}

  Update the specified webhook.

  This endpoint can be used to modify the callback url of the webhook or the type of events it must send, or to activate/deactivate it.

  A webhook can only be updated by its creator or by a user with Administrator access to the corresponding map.

  Arguments

  • webhookId (integer) :
    The webhook ID.

  Expected request body

  A Webhook object with its isActive, eventTypes and callbackUrl properties defined.

  Responses

  Status 200 - OK

  The updated Webhook.

• DELETE webhooks/{webhookId}

  Delete the specified webhook.

  A webhook can only be deleted by its creator or by a user with Administrator access to the corresponding map.

  Arguments

  • webhookId (integer) :
    The webhook ID.

  Responses

  Status 204 - NoContent

  Returned when the webhook was deleted.

Resource Types

• Map

  Represents a map.

  A map is a structured board of cards. The structure is defined as follows:

  Cards are organized into vertical lists. The cards inside these lists are called list items. The cards acting as header of one of these lists are called list headers.

  Lists are organized into groups, representing a higher level of hierarchy. Groups contain lists which contain items. The cards acting as header of one of these groups are called group headers.

  Furthermore, list items are divided into several horizontal layers. Layers exist independently from lists and groups and represent a different dimension inside the map. The cards acting as header of one of these layers are called layer headers.

  Finally, some cards may exist in the map without being part of the map structure. We say these cards are "on the bench", and we call them bench items. The bench has no header card.

  We say that the lists items are attached to a list header because moving the header card will move the items too. Similarly, the list headers are attached to a group header. The list items are also attached to a layer header.

  We can also say that the list contains some items and that these items are inside a list. All list items are inside a list and a layer at the same time.

  Properties

  • ownerName (string) : The map's owner name.

    A map's owner name is the username of that map's owner, i.e. the user who created that map. That user doesn't need to remain an active participant of that map.

    Along with the map's clean name, it constitutes the ID of the map.

  • cleanName (string) : The map's clean name.

    The clean name is a slug generated from the map's initial name. It corresponds to the initial name with no special characters and is used to form urls. For example the clean name of "My map 2.0" is "My-map-2-0". The clean name is NOT regenerated when the map's name changes.

    Along with the map's owner name, it constitutes the ID of the map.

  • uniqueId (string) : The map's unique ID.

    This ID is a generated unique identifier composed of 6 alphanumerical characters. Each map in the system has a different unique ID.

    Although this ID isn't used by the API endpoints to identify a map, it represents an alternative to the ownername/cleanName pair for your own purposes.

  • name (string) : The map's name.

    This is the name of the map as displayed on the user's dashboard and when editing this map.

  • groupsLabel (string) : The label used for Groups.

    This label is displayed in the top left corner of the map next to the GroupHeader cards (first hierarchy level).

  • listsLabel (string) : The label used for Lists.

    This label is displayed in the top left corner of the map next to the ListHeader cards (second hierarchy level).

  • layersLabel (string) : The label used for Layers.

    This label is displayed in the top left corner of the map above the LayerHeader cards (row headers).

  • isPublic (boolean) : Indicates if the map can be accessed publicly i.e. without having a FeatureMap account and without being invited to this map.

    When you create a new map it is considered private by default - however you can share it with the people of your choice.

    In the future marking a map as "public" will allow you to share it (as readonly) with anyone without required them to register to FeatureMap.

  • defaultEstimationLabel (string) : The default label of this map's cards Estimate field.

    This property can be used to define a default label for the estimation property of this map's cards.

    The label to use for a card's estimate is defined as followed:

    • use the card's estimationLabel property if it is not null
    • otherwise use the map's defaultEstimationLabel property if it is not null
    • otherwise use the text 'Estimate' (localized).
  • defaultEstimationUnit (string) : The default unit of this map's cards Estimate field.

    This property can be used to define a default unit for the estimation property of this map's cards.

    The unit to use for a card's estimate is defined as followed:

    • use the card's estimationUnit property if it is not null
    • otherwise use the map's defaultEstimationUnit property if it is not null
    • otherwise use no unit.
  • defaultBudgetLabel (string) : The default label of this map's cards Budget field.

    This property can be used to define a default label for the budget property of this map's cards.

    The label to use for a card's budget is defined as followed:

    • use the card's budgetLabel property if it is not null
    • otherwise use the map's defaultBudgetLabel property if it is not null
    • otherwise use no unit.
  • defaultBudgetUnit (string) : The default unit of this map's cards Budget field.

    This property can be used to define a default unit for the budget property of this map's cards.

    The unit to use for a card's budget is defined as followed:

    • use the card's budgetUnit property if it is not null
    • otherwise use the map's defaultBudgetUnit property if it is not null
    • otherwise use no unit.
  • cards (array of Cards) : The map's cards.

    This is the unordered list of cards in the map.

  • participants (array of MapParticipants) : The map's participants.

    This is the unordered list of participants in the map.
    Any user who once had access to this map is considered a participant of the map.

    Note that this list might contain users who no longer have access to this map. In that case the value of their MapParticipant.participantRole property will be "Revoked".

  • pendingInvitations (array of MapInvitations) : The map's pending invitations.
  • customProperties (object) : The map's custom properties.

    This property allows the user to associate custom properties to each map.
    These custom properties are organised as a set of key-value pairs represented by a javascript object; all keys and values are of type string.

    Example value: { "JiraProjectKey": "PRJ", "JiraProjectId": "123" }

• MapDescription

  Represents the description of a Map.

  A map's description is a brief summary of an existing map, meant to populate a list of maps.

  Properties

  • ownerName (string) : The map's owner name.

    A map's owner name is the username of that map's owner, i.e. the user who created that map. That user doesn't need to remain an active participant of that map.

    Along with the map's clean name, it constitutes the ID of the map.

  • ownerEmail (string) : The email address of the map's owner.
  • cleanName (string) : The map's clean name.

    The clean name is a slug generated from the map's initial name. It corresponds to the initial name with no special characters and is used to form urls. For example the clean name of "My map 2.0" is "My-map-2-0". The clean name is NOT regenerated when the map's name changes.

    Along with the map's owner name, it constitutes the ID of the map.

  • uniqueId (string) : The map's unique ID.

    This ID is a generated unique identifier composed of 6 alphanumerical characters. Each map in the system has a different unique ID.

    Although this ID isn't used by the API endpoints to identify a map, it represents an alternative to the ownername/cleanName pair for your own purposes.

  • name (string) : The map's name.

    This is the name of the map as displayed on the user's dashboard and when editing this map.

  • isPublic (boolean) : Indicates if the map can be accessed publicly i.e. without having a FeatureMap account and without being invited to this map.

    When you create a new map it is considered private by default - however you can share it with the people of your choice.

    In the future marking a map as "public" will allow you to share it (as readonly) with anyone without required them to register to FeatureMap.

  • isDemo (boolean) : Indicates if this map was created by cloning a demo/tutorial map.
  • nbrParticipants (integer) : The number of active participants in this map.
  • nbrCards (integer) : The number of cards in this map.
  • nbrLayers (integer) : The number of layers in this map.
  • lastEditionDateTime (datetime) : The timestamp of the last editing action on this map.
  • participantRole (string) : The role of the current user as a participant of this map (Viewer, Editor or Administrator).
  • isParticipantSuspended (boolean) : Indicates if the current user's access to this map is suspended. This can happen when his/her subscription expires.

• MapParticipant

  Represents a participant to a map.

  A map participant is a user who have (or had) access to the map.

  Their role (participantRole) indicates the level of access they have upon a map and its content.

  Properties

  • username (string) : The username, a unique user identifier.
  • email (string) : The user's email address.
  • firstName (string) : The user's first name.
  • lastName (string) : The user's last name.
  • preferredCulture (string) : The user's preferred culture (language), if known.

    Examples: "en-US" (American English), "fr-FR" (French), "zh-CN" (simplified Chinese).

  • shortDisplayName (string) : The user's short display name.

    This is a short representation of the user's name. It is generally based on the first name. Example: John.

  • displayName (string) : The user's display name.

    This is a long representation of the user's name. It is generally based on the first name and the last name. Example: John Doe.

  • usesGravatar (boolean) : Indicates whether Gravatar must be used to retrieve the user profile image (avatar) based on his email address.
  • timeZone (string) : The user timezone.

    This is the name of the user timezone, as defined by the tz database. Example: "America/New_York".

  • uploadedAvatarKey (string) : The file key of the uploaded profile image, if there is one.

    If the user doesn't want to use Gravatar as profile image, he must upload a custom image to use instead. In that case this property will provide the key of the uploaded file in order to fetch the uploaded image from FeatureMap's servers. The URL path to the image is https://www.featuremap.co/files/{username}/{uploadedAvatarKey}. You can also obtain a thumbnail of a specific size using https://www.featuremap.co/thumbs/{username}/{uploadedAvatarKey}/{size}.

  • notificationEmailFrequency (string) : The frequency at which the user wants to receive notification emails.

    This property can have one of the following values:

    • "Immediately": send an email as soon as a new notification comes up.
    • "Every2Hours": send an email with the new notifications that came up during the last 2 hours (if any).
    • "Everyday": send an email once per day at 8 AM (local time).
    • "Never": do not send emails.
  • activeLicenceType (string) : The current license type of the user.

    This property can have one of the following values:

    • "None": this user has no active license and will have to subscribe to an offer before he can use the app.
    • "Free": this user is using a free (limited) license.
    • "Trial": this user is currently using the app with a free trial license.
    • "Premium": this user has a Premium license.
  • participantRole (string) : The role of this participant.

    This property can have one of the following values:

    • "Viewer": the user has readonly access to the map and its content.
    • "Editor": the user can modify the map and its content.
    • "Administrator": the user can modify the map and its content, and can manage the map participants and their rights.
    • "Revoked": the user has no longer access to this map.

• MapInvitation

  Represents an invitation to join a map.

  A map invitation is created whenever a user was invited to join a map but didn't create a user account yet.

  When the user signs up using the email address the invitation was sent to, the invitation is automatically converted into a MapParticipant and the new user immediately gains access to the map.

  Properties

  • email (string) : The mail address this invitation was sent to.
  • message (string) : The message included in the invitation.
  • participantRole (string) : The role the user will have for this map after signup.

    Possible values: "Viewer", "Editor", "Administrator".

• Card

  Represents a card.

  A card is a unit of content inside a map.

  Each card has a specific role depending on its position inside the map's structure (see CardPosition).

  A card has several describing properties such as description, color, and status. It can also have comments, attachments or a checklist.

  A card can have custom properties and a key. These properties can be used to associate additional data to each item in the list. For example when a map is synchronized to a project from Atlassian JIRA, each checklist item in a card is linked to a sub-task issue in JIRA. The key of the item corresponds to the issue's key, and the custom properties indicate the issue's ID.

  Properties

  • id (integer) : The card's ID.

    This ID is unique to the map containing the card. Different cards of the same map will have different IDs, but different cards of different maps may have the same ID.

  • uniqueId (string) : The card's unique ID.

    This ID is a generated unique identifier composed of 6 alphanumerical characters. Each card in the system has a different unique ID.

    Although this ID isn't used by the API endpoints to identify a card, it represents an alternative to the mapOwnername/mapCleanName/id triplet for your own purposes.

  • role (string) : The card's role.

    The role of a card is one of the properties defining its position (location) in the map. See CardPosition for details.

  • parentCardId (integer) : The ID of the card's parent.

    The parent of a card is one of the properties defining its position (location) in the map. See CardPosition for details.

  • otherParentCardId (integer) : The ID of the card's other parent.

    The other parent of a card is one of the properties defining its position (location) in the map. See CardPosition for details.

  • index (integer) : The card's index.

    The index of a card is one of the properties defining its position (location) in the map. See CardPosition for details.

  • isVirtual (boolean) : Indicates if the card is virtual.

    A card is virtual when it acts as a placeholder for a group header, a list header or a layer header.

    A virtual card has no title and no content. It can be the parent of other cards.

  • key (string) : An optional reference for this card.

    This property can be used to store and external reference for this card and is displayed in front of the card's title in the checklist.

    For example when a card is linked to a JIRA issue its key property will be the key of that issue.

  • title (string) : The card's title.
  • description (string) : The card's description.
  • importance (string) : The card's importance (priority).

    This property can have one of the following values:

    • "low"
    • "medium"
    • "high"
  • estimation (string) : The card's estimate.

    Although the value can be an arbitrary string, a numerical value will most likely be used.

  • estimationMode (string) : The card's estimate mode (either free text or computed).

    This property can be either "free" or "sum".

    If the value of this property is "free", the value of the estimation property will be used to display the card's estimate. If the value is "sum", the value displayed will be the sum of the estimates of all the cards attached to this card.

  • estimationLabel (string) : The card's estimate label.

    This is the label for the estimate property of this card.

    If the value of this property is null, the map's defaultEstimationLabel will be used. If that property is null too, the text "Estimate" (localized) will be used.

  • estimationUnit (string) : The card's estimate unit.

    This property can have one of the following values:

    • "none" (no unit)
    • "points"
    • "euros"
    • "dollars"
    • "weeks"
    • "days"
    • "hours"
  • budget (string) : The card's budget.

    Although the value can be an arbitrary string, a numerical value will most likely be used.

  • budgetMode (string) : The card's budget mode (either free text or computed).

    This property can be either "free" or "sum".

    If the value of this property is "free", the value of the budget property will be used to display the card's budget. If the value is "sum", the value displayed will be the sum of the budgets of all the cards attached to this card.

  • budgetLabel (string) : The card's budget label.

    This is the label for the budget property of this card.

    If the value of this property is null, the map's defaultBudgetLabel will be used. If that property is null too, the text "Budget" (localized) will be used.

  • budgetUnit (string) : The card's budget unit.

    This property can have one of the following values:

    • "none" (no unit)
    • "points"
    • "euros"
    • "dollars"
    • "weeks"
    • "days"
    • "hours"
  • status (string) : The card's status.

    This property can have one of the following values:

    • null (no status)
    • "todo"
    • "ongoing"
    • "done"
    • "cancelled"
    • "blocked"
    • "aggregated"
  • color (string) : The card's color.

    This property can have one of the following values:

    • null (no color)
    • "green"
    • "yellow"
    • "orange"
    • "red"
    • "pink"
    • "purple"
    • "blue"
    • "darkBlue"
    • "white"
  • owner (string) : The card's owner.

    When the card's owner is a user, the value of this property is that user's username.

  • dueDate (datetime) : The card's due date.
  • creationDateTime (datetime) : The card's creation timestamp.
  • lastEditionDateTime (datetime) : The card's last edition timestamp.
  • creatorName (string) : The username of the card's creator.
  • nbrComments (integer) : The number of comments on this card.

    This property is updated automatically when comments are added to or removed from the card.

  • nbrAttachments (integer) : The number of attachments on this card.

    This property is updated automatically when attachments are added to or removed from the card.

  • nbrCheckListItems (integer) : The number of checklist items on this card.

    This property is updated automatically when checklist items are added to or removed from the card.

  • nbrDoneCheckListItems (integer) : The number of checklist items on this card that are considered "done".

    This property is updated automatically when checklist items are added to or removed from the card, or when the isDone property of an item changes.

  • comments (array of Comments) : The set of comments of this card.
  • attachments (array of Attachments) : The set of attachments of this card.
  • checklist (array of CheckListItems) : The checklist of this card.
  • subscriberNames (array of strings) : The usernames of the user who subscribed to this card.
  • customProperties (object) : This card's custom properties.

    This property allows the user to associate custom properties to each card.
    These custom properties are organised as a set of key-value pairs represented by a javascript object; all keys and values are of type string.

    Example value: { "JiraIssueKey": "PRJ-012", "JiraIssueId": "256" }

• CardPosition

  Represents the position of a card.

  The position of a card in a map is given by 4 properties.

  The card's role describes its position as part of the map's structure (see Map). It can be one of the following 5 strings:

  • "GroupHeader"
  • "ListHeader"
  • "LayerHeader"
  • "ListItem"
  • "BenchItem"

  The card's parent is the header card the card is attached to (vertically). For list items, the parent is a list header. For list header, the parent is a group header. Group headers, layer headers and bench items have no parent.

  The card's other parent is the "other" header card the card is attached to (horizontally). For list items, the other parent is a layer header. All the other cards have no other parent.

  The card's index is the order in which cards having the same role and parents are presented.

  Properties

  • role (string) : The card's role.

    The role of a card's describes its position as part of the map's structure (see Map).

    It can be one of the following 5 strings:

    • "GroupHeader"
    • "ListHeader"
    • "LayerHeader"
    • "ListItem"
    • "BenchItem"
  • parentCardId (integer) : The ID of the card's parent.

    This property indicates the ID of the card's parent.

    The card's parent is the header card the card is attached to (vertically). For list items, the parent is a list header. For list header, the parent is a group header. Group headers layer headers and bench items have no parent, therefore the value of this property is null for these cards.

  • otherParentCardId (integer) : The ID of the card's other parent.

    This property indicates the ID of the card's other parent.

    The card's other parent is the "other" header card the card is attached to (horizontally). For list items, the other parent is a layer header. All the other cards have no other parent, therefore the value of this property is null for these cards.

  • index (integer) : The card's index.

    The index of a card's is the order in which cards having the same role and parents are presented.

    For example if there are two groups in the map they will both have the role "GroupHeader" and they will both have no parents, but the first group header will have index 0 and the other will have index 1.

    List items inside the same list and layer also have the same role and parents but different indices.

• Comment

  Represents a comment on a card.

  Properties

  • id (integer) : The comment's ID.

    This ID is unique to the card holding the comment. Different comments of the same card will have different IDs, but different comments of different cards may have the same ID.

  • message (string) : The comment's message.
  • authorName (string) : The username of the user who posted the comment.
  • creationDateTime (datetime) : The moment this comment was created.
  • lastEditionDateTome (datetime) : The moment this comment was edited (or created) for the last time.

• Attachment

  Represents an attachment (link or file) on a card.

  An attachment is either an hyperlink (URL) or an uploaded file. The value of its type property will be "Link" or "File" accordingly.

  When the attachment represents an uploaded file, that file can be downloaded at https://www.featuremap.co/files/{ownerName}/{fileKey} where {ownerName} is the username of the user who uploaded the file (and thus created the attachment) and {fileKey} is the value given by the attachment's fileKey property.

  Properties

  • id (integer) : The attachment's ID.

    This ID is unique to the card holding the attachment. Different attachments of the same card will have different IDs, but different attachments of different cards may have the same ID.

  • type (string) : The attachment's type (File or Link).

    When the type is File, this attachment represents an attached file and the ownerName, fileContentType, fileSize and fileKey properties will provide the necessary info about the file itself and how to retrieve it.

    When the type is Link, this attachment represents an attached link and the property linkUrl will provide the corresponding URL.

  • name (string) : The attachment's display name.

    For File attachments, this property holds the name of the attached file.

  • ownerName (string) : The username of the user who created this attachment.
  • uploadDateTime (datetime) : The moment this attachment was created.

    For File attachments, this property represents the moment the file was uploaded.

  • linkUrl (string) : The URL of the attached link.

    This property is null when the attachment's type is File.

  • fileContentType (string) : The MIME type of the attached file.

    This property is null when the attachment's type is Link.

  • fileSize (integer) : The size of the attached file, in bytes.

    This property is null when the attachment's type is Link.

  • fileKey (string) : The key of the attached file.

    The attached file can be downloaded at this URL: https://www.featuremap.co/files/{ownerName}/{fileKey}.

    This property is null when the attachment's type is Link.

• CheckListItem

  Represents an item of the checklist of a card.

  A card checklist is made of several items.

  Each item has a content (text), an index representing its position in the list, and a state (isDone) indicating whether the item is considered done (checked).

  An item can also have custom properties and a key. These properties can be used to associate additional data to each item in the list. For example when a map is synchronized to a project from Atlassian JIRA, each checklist item in a card is linked to a sub-task issue in JIRA. The key of the item corresponds to the issue's key, and the custom properties indicate the issue's ID.

  Properties

  • id (integer) : The item's ID.

    This ID is unique to the card holding the checklist. Different items of the same card will have different IDs, but different items of different cards may have the same ID.

  • index (integer) : The item's position in the list.

    Each item in the checklist has a different 0-based index indicating its position in the list.

  • content (string) : The item's content.

    This is the text of the item as displayed in the list.

  • isDone (boolean) : Indicates whether the item is considered done (checked).
  • key (string) : An optional reference for this item.

    This property can be used to store and external reference for this item and is displayed in front of the item's content in the checklist.

    For example when an item is linked to a JIRA issue its key property will be the key of that issue.

  • customProperties (object) : The item's custom properties.

    This property allows the user to associate custom properties to each checklist item.
    These custom properties are organised as a set of key-value pairs represented by a javascript object; all keys and values are of type string.

    Example value: { "JiraIssueKey": "PRJ-012", "JiraIssueId": "256" }

• ActivitylogEntry

  Represents an entry in the activity log of a map.

  The activity log of a map is the history of all the actions made on that map. Each recorded action is represented by an Event. Each entry of the log designates a specific Event.

  Properties

  • id (integer) : The entry's ID.

    This ID is unique to the map. Different log entries of the same map will have different IDs, but different entries of different maps may have the same ID.

  • event (Event) : The Event designated by this entry.

• User

  Represents a registered user of the application.

  Properties

  • username (string) : The username, a unique user identifier.
  • email (string) : The user's email address.
  • firstName (string) : The user's first name.
  • lastName (string) : The user's last name.
  • shortDisplayName (string) : The user's short display name.

    This is a short representation of the user's name. It is generally based on the first name. Example: John.

  • displayName (string) : The user's display name.

    This is a long representation of the user's name. It is generally based on the first name and the last name. Example: John Doe.

  • company (string) : The user 's company name.
  • role (string) : The user 's role inside his company.
  • preferredCulture (string) : The user's preferred culture (language), if known.

    Examples: "en-US" (American English), "fr-FR" (French), "zh-CN" (simplified Chinese).

  • usesGravatar (boolean) : Indicates whether Gravatar must be used to retrieve the user profile image (avatar) based on his email address.
  • uploadedAvatarKey (string) : The file key of the uploaded profile image, if there is one.

    If the user doesn't want to use Gravatar as profile image, he must upload a custom image to use instead. In that case this property will provide the key of the uploaded file in order to fetch the uploaded image from FeatureMap's servers. The URL path to the image is https://www.featuremap.co/files/{username}/{uploadedAvatarKey}. You can also obtain a thumbnail of a specific size using https://www.featuremap.co/thumbs/{username}/{uploadedAvatarKey}/{size}.

  • timeZone (string) : The user timezone.

    This is the name of the user timezone, as defined by the tz database. Example: "America/New_York".

  • notificationEmailFrequency (string) : The frequency at which the user wants to receive notification emails.

    This property can have one of the following values:

    • "Immediately": send an email as soon as a new notification comes up.
    • "Every2Hours": send an email with the new notifications that came up during the last 2 hours (if any).
    • "Everyday": send an email once per day at 8 AM (local time).
    • "Never": do not send emails.
  • activeLicenceType (string) : The current license type of the user.

    This property can have one of the following values:

    • "None": this user has no active license and will have to subscribe to an offer before he can use the app.
    • "Free": this user is using a free (limited) license.
    • "Trial": this user is currently using the app with a free trial license.
    • "Premium": this user has a Premium license.

• Group

  Represents a user group.

  A user group represents a team of FeatureMap users.

  A group can have a treasurer. In that case whenever a new member is added to the group his subscription will be managed by the treasurer.

  Note: User groups are not to be confused with groups of card lists inside a map, i.e. cards having the GroupHeader role.

  Properties

  • ownerName (string) : The group's owner name.

    A group's owner name is the username of that group's owner, i.e. the user who created that group. That user doesn't need to remain a member of that group.

    Along with the group's clean name, it constitutes the ID of the group.

  • cleanName (string) : The group's clean name.

    The clean name is a slug generated from the group's initial name. It corresponds to the initial name with no special characters and is used to form urls. For example the clean name of "My group 2.0" is "My-group-2-0". The clean name is NOT regenerated when the group's name changes.

    Along with the group's owner name, it constitutes the ID of the group.

  • name (string) : The group's name.

    This is the name of the group as displayed on the user's dashboard and when editing this group.

  • treasurerName (string) : The username of the group's treasurer.

    The group's treasurer is the person generally holding the credit card.

    Whenever a new member is added to the group his subscription will be managed by the treasurer.

  • participants (array of GroupParticipants) : The group's participants.

    This is the unordered list of participants in the group.
    Any user who was once a member of this group is considered a participant of the group.

    Note that this list might contain users who are no longer a member of this group. In that case the value of their GroupParticipant.participantRole property will be "Revoked".

  • pendingInvitations (array of GroupInvitations) : The group's pending invitations.

• GroupParticipant

  Represents a participant to a group.

  A group participant is a user who is (or was) a member of the group.

  Their role (participantRole) indicates the privileges they have upon the group and its members.

  Properties

  • username (string) : The username, a unique user identifier.
  • email (string) : The user's email address.
  • firstName (string) : The user's first name.
  • lastName (string) : The user's last name.
  • preferredCulture (string) : The user's preferred culture (language), if known.

    Examples: "en-US" (American English), "fr-FR" (French), "zh-CN" (simplified Chinese).

  • shortDisplayName (string) : The user's short display name.

    This is a short representation of the user's name. It is generally based on the first name. Example: John.

  • displayName (string) : The user's display name.

    This is a long representation of the user's name. It is generally based on the first name and the last name. Example: John Doe.

  • usesGravatar (boolean) : Indicates whether Gravatar must be used to retrieve the user profile image (avatar) based on his email address.
  • timeZone (string) : The user timezone.

    This is the name of the user timezone, as defined by the tz database. Example: "America/New_York".

  • uploadedAvatarKey (string) : The file key of the uploaded profile image, if there is one.

    If the user doesn't want to use Gravatar as profile image, he must upload a custom image to use instead. In that case this property will provide the key of the uploaded file in order to fetch the uploaded image from FeatureMap's servers. The URL path to the image is https://www.featuremap.co/files/{username}/{uploadedAvatarKey}. You can also obtain a thumbnail of a specific size using https://www.featuremap.co/thumbs/{username}/{uploadedAvatarKey}/{size}.

  • notificationEmailFrequency (string) : The frequency at which the user wants to receive notification emails.

    This property can have one of the following values:

    • "Immediately": send an email as soon as a new notification comes up.
    • "Every2Hours": send an email with the new notifications that came up during the last 2 hours (if any).
    • "Everyday": send an email once per day at 8 AM (local time).
    • "Never": do not send emails.
  • activeLicenceType (string) : The current license type of the user.

    This property can have one of the following values:

    • "None": this user has no active license and will have to subscribe to an offer before he can use the app.
    • "Free": this user is using a free (limited) license.
    • "Trial": this user is currently using the app with a free trial license.
    • "Premium": this user has a Premium license.
  • participantRole (string) : The role of this participant.

    This property can have one of the following values:

    • "Member": the user is a regular member of the group.
    • "Administrator": the user can modify the group properties and manage the group participants and their rights.
    • "Revoked": the user is no longer a member of this group.

• GroupInvitation

  Represents an invitation to join a group.

  A group invitation is created whenever a user was invited to join a group but didn't create a user account yet.

  When the user signs up using the email address the invitation was sent to, the invitation is automatically converted into a GroupParticipant and the new user immediately gains access to the group.

  Properties

  • email (string) : The mail address this invitation was sent to.
  • message (string) : The message included in the invitation.
  • participantRole (string) : The role the user will have for this group after signup.

    Possible values: "Member", "Administrator".

• Notification

  Represents a user notification.

  A notification is a message addressed to a user to inform him/her that a specific event has occurred.

  Properties

  • id (integer) : The notification's ID.

    This ID is unique.

  • isRead (boolean) : Indicates whether this notification has been read.
  • event (Event) : The Event designated by this notification.

• Event

  Represents an action made upon the content of a map.

  FeatureMap records all kinds of events. For example when a user creates a card, changes the color of a card, edits a comment, or shares a map with a coworker each action is recorded along with the corresponding data.

  Events may concern a specific map, or a specific card. In that case the map ID and/or the card ID is provided.

  Depending on the event's type, some data may be stored in the data property. For example when the color of a card is changed, the data property will contain the old and new color names.

  Properties

  • authorName (string) : The username of the user who initiated the event.

    This property can be null if the event was initiated automatically, e.g. when the event concerns an upcoming due date.

  • authorDisplayName (string) : The full name of the user who initiated the event.

    This property can be null if the event was initiated automatically, e.g. when the event concerns an upcoming due date.

  • timestamp (datetime) : The event timestamp.
  • type (string) : The event type.

    Here is the exhaustive list of the existing event types, along with their corresponding data:

    • MapCreated: newMapName
    • MapNameUpdated: oldMapName, newMapName
    • MapGroupsLabelUpdated: oldLabel, newLabel
    • MapListsLabelUpdated: oldLabel, newLabel
    • MapLayersLabelUpdated: oldLabel, newLabel
    • MapParticipantInvited: newParticipantName, message, addedUsername?
    • MapParticipantKicked: oldParticipantName
    • MapParticipantLeft: oldParticipantName
    • CardAdded: newCardId, newCardTitle, parentCardId, otherParentCardId, role, index
    • CardMoved: updatedProperties, oldParentCardId?, parentCardId?, newParentCardId?, oldParentCardTitle?, parentCardTitle?, newParentCardTitle?, oldOtherParentCardId?, otherParentCardId?, newOtherParentCardId?, oldOtherParentCardTitle?, otherParentCardTitle?, newOtherParentCardTitle?
    • CardUpdated: updatedProperties, oldTitle?, newTitle?, oldDescription?, newDescription?, oldDueDate?, newDueDate?, oldEstimation?, newEstimation?, oldBudget?, newBudget?, oldImportance?, newImportance?, oldOwner?, newOwner?, newOwnerIsMapParticipant?, oldStatus?, newStatus?, oldColor?, newColor? (see below)
    • CardDeleted: cardTitle, cardSubscribers
    • CardStarted: updatedProperties, oldStatus, newStatus
    • CardCompleted: updatedProperties, oldStatus, newStatus
    • CardCancelled: updatedProperties, oldStatus, newStatus
    • CardOverdue: mapName, cardTitle, dueDate
    • CardDueToday: mapName, cardTitle, dueDate
    • CardDueTomorrow: mapName, cardTitle, dueDate
    • CardDueInOneWeek: mapName, cardTitle, dueDate
    • CommentAdded: commentMessage, newMentionedUsers
    • CommentUpdated: newCommentMessage, oldCommentMessage, oldMentionedUsers, mentionedUsers, newMentionedUsers
    • CommentDeleted: commentMessage, oldMentionedUsers
    • AttachmentAdded: attachmentType, attachmentName
    • AttachmentDeleted: attachmentType, attachmentName
    • CheckListItemAdded: itemId, itemContent
    • CheckListItemContentUpdated: itemId, oldItemContent, itemContent, newItemContent
    • CheckListItemDone: itemId, itemContent
    • CheckListItemUndone: itemId, itemContent
    • CheckListItemDeleted: itemId, itemContent

    Data property names suffixed with a quotation mark in this documentation are optional. They may be absent depending on the context.

    In the case of the CardUpdated event type, the value of "updatedProperties" will be a concatenated list of the names of the updated card properties.
    For example if only the color of a card was changed, the value of "updatedProperties" will be "Color" and the "oldColor" and "newColor" properties will be defined.
    If the color and the title were changed at the same time, the value of "updatedProperties" will be "Title,Color" and the "oldTitle", "newTitle", "oldColor" and "newColor" properties will be defined.

  • data (object) : An object representing the event data.
  • mapOwnerName (string) : The owner name of the map concerned by the event.

    If the event does not concern a specific map, the value of this property is null.

  • mapCleanName (string) : The clean name of the map concerned by the event.

    If the event does not concern a specific map, the value of this property is null.

  • mapUniqueId (string) : The unique ID of the map concerned by the event.

    If the event does not concern a specific map, the value of this property is null.

  • cardId (integer) : The ID of the card concerned by the event.

    If the event does not concern a specific card, the value of this property is null.

  • cardUniqueId (string) : The unique ID of the card concerned by the event.

    If the event does not concern a specific map, the value of this property is null.

• Webhook

  Represents a webhook.

  Webhooks can send events to the URL of your choice. They can only monitor a single map at a time.

  A webhook can track several types of events. You can have multiple webhooks on the same map tracking identical or different types of events.

  Webhooks can be active or inactive. A webhook won't send events when it is not active.

  If the Premium license of the user who created this webhook expires, the webhook won't be sending events anymore.

  Properties

  • id (int) : The webhook's ID.

    This ID is unique.

  • mapOwnerName (string) : The owner name of the map monitored by the webhook.
  • mapCleanName (string) : The clean name of the map monitored by the webhook.
  • creatorName (string) : The username of the user who created this webhook.

    Important: if the Premium license of the user who created this webhook expires, the webhook won't be sending events anymore.

  • creationDateTime (datetime) : The moment this webhook was created.
  • eventTypes (string) : The list of event types monitored by this webhook.

    This is a comma-separated list of the types of events monitored by this webhook.

    Here is the exhaustive list of available event types:

    • MapUpdated: Some properties of the map were updated (name, groups label, lists label etc).
    • MapParticipantAdded: A new participant has joined the map.
    • MapParticipantUpdated: The role or access of one of the participant has changed.
    • CardAdded: A new card has been added. This card may be virtual.
    • RealCardAdded: A new (non virtual) card has been added OR a virtual card is no longer virtual.
    • CardMoved: A card has been moved to another position in the map.
    • CardUpdated: Some properties of a card were updated (title, description, status, color etc).
    • CardDeleted: A card was deleted.
    • CardStatusUpdated: The status of a card has changed.
    • CommentAdded: A comment was added to a card.
    • CommentUpdated: The message of a comment has been updated.
    • CommentDeleted: A comment has been deleted.
    • AttachmentAdded: An attachement (link or file) has been added to a card.
    • AttachmentDeleted: A attachment has been deleted.
    • CheckListItemAdded: A checklist item has been added to a card.
    • CheckListItemContentUpdated: The content of a checklist item has been updated.
    • CheckListItemStatusUpdated: The status (done/undone) of a checklist item has been updated.
    • CheckListItemDeleted: A checklist item has been deleted.
    • ActivityLogEntryAdded: An entry was added into the map's activity log.
  • callbackUrl (string) : The URL to which the events should be sent.

    The webhooks will send POST requests to this URL. The body of each request will be a single JSON oject with the following properties:

    • type: The event type.
    • timestamp: The moment that event occurred.
    • data: Information about the event.

    The "data" property will be a JSON object describing the event. Depending on the type of the event certain properties will be defined. Here is the list of potential properties:

    • mapOwnerName: The owner name of the map.
    • mapCleanName: The clean name of the map.
    • map: The Map. Only defined when the event is related to the map itself.
    • cardId: A card ID. Only defined when the event is related to a specific card.
    • card: A Card. Only defined when the event is related to a specific card.
    • commentId: A comment ID. Only defined when the event is related to a specific comment.
    • comment: A Comment. Only defined when the event is related to a specific comment.
    • attachmentId: A attachment ID. Only defined when the event is related to a specific attachment.
    • attachment: An Attachment. Only defined when the event is related to a specific attachment.
    • itemId: A checklist item ID. Only defined when the event is related to a specific item.
    • item: A CheckListItem. Only defined when the event is related to a specific item.
    • entryId: An activity log entry ID. Only defined when the event is related to a specific entry.
    • entry: An ActivitylogEntry. Only defined when the event is related to a specific entry.
    • entryMessage: The message of the activity log entry (using markdown). Only defined when the event is related to a specific entry.
  • isActive (boolean) : Indicates whether this webhook is active.

    The webhook won't send events when it is not active.