Crumbs is being retired on 31 December 2024. Read the announcement here

1 API Base URL
2 API Tokens
3 Authentication
4 Authorization
5 API Resources
- 5.1 Customer /customer
  - 5.1.1 Get Customers
  - 5.1.2 Get Customer
  - 5.1.3 Create Customer
  - 5.1.4 Update Customer
  - 5.1.5 Delete Customer
- 5.2 Field /field
  - 5.2.1 Get Fields
  - 5.2.2 Get Field
- 5.3 Issue Link /issueLink
  - 5.3.1 Get Issue Links
  - 5.3.2 Create issue Link
  - 5.3.3 Delete Issue Link
- 5.4 Note /note
  - 5.4.1 Get Notes
  - 5.4.2 Create Note
  - 5.4.3 Update Note
  - 5.4.4 Delete Note
6 Types
- 6.1 Customer
- 6.2 Field Values
- 6.3 Field Value
- 6.4 Field
- 6.5 Field Type
- 6.6 Field Configuration
- 6.7 Select Field Option
- 6.8 Issue Links
- 6.9 Issue Link
- 6.10 Note

This document provides public documentation of the Crumbs API.

API Base URL

The API is accessible via:

https://crumbs.newverve.scot/api/1/<resource>

API Tokens

To generate a new API token, go to the API Tokens section in Crumbs (in Jira, select Apps > Crumbs > API Tokens):

These tokens will allow users to authenticate against the Crumbs API.

From this screen users will be able to:

Create new tokens with a label.
View the newly created token (only on generation for security reasons).
1. Please take note of the token when creating it and keep it safe.
View previously generated tokens by their label.
View when the token was created.
Users can delete/revoke a previously generated token.

Tokens are user specific, and each user can create and see only their API tokens.

Authentication

Use the Authorization HTTP header to submit.

Use Bearer <token>, and add the token generated in API Tokens screen.

For example with cURL:

curl --request GET 'https://crumbs.newverve.scot/api/1/customer/1' \
--header 'Authorization: Bearer 1c831a91-3559-475e-b4d4-39efd65b9d94'

Authorization

All API resources are authorised against Jira users who have generated any Crumbs tokens, following general Crumbs permissions:

Crumbs Administrator
Crumbs Manager
Crumbs User

Please check Crumbs documentation to find out more about Crumbs permissions, and check Jira permissions (or contact your Jira administrator) to verify the Crumbs permissions of your user.

Please check the resources section in this document to find specific permissions needed for each resource.

API Resources

Resources currently available:

Customer `/customer`

Represents customers created in Crumbs and in JSM (only JSM Organizations with Crumbs fields saved against them will show up).

Resource Description	Request Details	Response Details

Resource Description

Request Details

Response Details

Get Customers

GET /customer

Returns a list of Crumbs customers. startAt can be specified to return the list starting at any required point.

Only returns JSM organizations with data added in Crumbs.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager
Crumbs User

Query parameters:

startAt - integer
- The customer to start at
fields - Array<string>
- Only include specific fields
- Array of field ids
- If omitted, return all fields

Input or request example:

startAt=0
fields=address, mainContact, name, eb7e4568-d283-4329-8805-d3b4c4983f1d

cURL:

curl \
--request GET 'https://crumbs.newverve.scot/api/1/customer?startAt=0&fields=address,mainContact,name,eb7e4568-d283-4329-8805-d3b4c4983f1d' \
--header 'Authorization: Bearer 1c831a91-3559-475e-b4d4-39efd65b9d94'

200 - Array<Customer>

Output or response example:

eb7e4568-d283-4329-8805-d3b4c4983f1d here represents the id of a multi select field in Crumbs

[
  {
    "id": "customerId-1",
    "fields": {
      "name": "Customer A",
      "website": "http://www.example.com",
      "description": "An example customer",
      "address": "1 Example Street",
      "region": "Example region",
      "zipCode": "A12 3BC",
      "city": "A City",
      "country": "A Country",
      "mainContact": "accountId-1",
      "eb7e4568-d283-4329-8805-d3b4c4983f1d": [
        {
          "id": "abb7bab8-5cbe-4642-b728-90107029b4d4",
          "value": "Option 1"
        }
      ]
    }
  },
  {...},
]

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

Get Customer

GET /customer/{customerId}

Returns the queried customer details.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager
Crumbs User

Path parameters:

customerId - string
- The id of the customer
- Crumbs id or JSM id
fields - Array<string>
- Only include specific fields
- Array of field ids
- If omitted, return all fields

Input or request example:

customerId can be an alphanumeric id for a Crumbs customer 75aaaeeb-c871-4d9e-904b-10e07a639103 or a number for a JSM customer 120
fields=address, mainContact, name, eb7e4568-d283-4329-8805-d3b4c4983f1d

cURL:

200 - Customer

Output or response example:

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the customer is not found.

Create Customer

POST /customer

Creates a new Crumbs customer

Permissions required, only:

Crumbs Administrator
Crumbs Manager

Body - Field Values

Input or request example:

cURL:

201 - Customer

Output or response example:

400

Returned if the request:

the request body is missing.
is missing required fields.
contains invalid field values.
contains fields that cannot be set.
is invalid for any other reason.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

Update Customer

PUT /customer/{customerId}

Updates an existing Crumbs customer

Cannot rename JSM organizations due to API limitations.

Permissions required, only:

Crumbs Administrator
Crumbs Manager

Path parameters:

customerId - string
- The id of the customer
- Crumbs id or JSM id

Body - Field Values

Input or request example:

cURL:

204

Successful request will only return 204 with no other output.

400

Returned if:

the request body is missing.
is missing required fields.
contains invalid field values.
contains fields that cannot be set.
is invalid for any other reason.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the customer is not found.

Delete Customer

DELETE /customer/{customerId}

Deletes a specific Crumbs customer

Permissions required, only:

Crumbs Administrator
Crumbs Manager

Path parameters:

customerId - string
- The id of the customer
- Crumbs id or JSM id

Input or request example:

cURL:

204

Successful request will only return 204 with no other output.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the customer is not found.

Field `/field`

The definition of all fields.

Description	Request Details	Response Details

Description

Request Details

Response Details

Get Fields

GET /field

Get all fields.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager
Crumbs User

Input or request example:

cURL:

200 - Array<Field>

Output or response example:

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

Get Field

GET /field/{fieldId}

Get field.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager
Crumbs User

Path parameters:

fieldId - string
- The id of the field

Input or request example:

fieldId an alphanumeric id for a Crumbs field, e.g. 75aaaeeb-c871-4d9e-904b-10e07a639103

cURL:

200 - Field

Output or response example:

400

Returned if input incorrect format.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the field cannot be found.

Issue Link `/issueLink`

View, link and unlink customers to issues.

Description	Request Details	Response Details

Description

Request Details

Response Details

Get Issue Links

GET /issueLink/{issueIdOrKey}

Get customers linked to an issue.

Permissions required, only:

Crumbs Administrator
Crumbs Manager
Crumbs User

Path parameters:

issueIdOrKey - string
- The id or key of the issue to view the links for

Input or request example:

issueIdOrKey usually a 5 digit number, e.g. 10023 or the project key + issue number e.g. GSP-118. Jira uses both ways to point to the same issue.

cURL:

200 - Issue Links

Output or response example:

400

Returned if input incorrect format.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the issue is not found.

Returned if the user does not have permission to browse the issue.

Create issue Link

POST /issueLink/{issueIdOrKey}

Link a customer to an issue.

Permissions required, only:

Crumbs Administrator
Crumbs Manager
Crumbs User

Path parameters:

issueIdOrKey - string
- The id or key of the issue to link a customer to

Body - Issue Link

cURL:

201

Successful request will only return 201 with no other output.

400

Returned if input incorrect format.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the issue or customer is not found.

Returned if the user does not have permission to browse the issue.

Delete Issue Link

DELETE /issueLink/{issueIdOrKey}

Unlink a customer from an issue.

Permissions required, only:

Crumbs Administrator
Crumbs Manager
Crumbs User

Path parameter:

issueIdOrKey - string
- The id or key of the issue to link a customer from

Body - Issue Link

cURL:

204

Successful request will only return 204 with no other output.

400

Returned if input incorrect format.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the issue or customer is not found.

Returned if the user does not have permission to browse the issue.

Note `/note`

View, edit, delete notes.

Description	Request Details	Response Details

Description

Request Details

Response Details

Get Notes

GET /note

Get all notes for a customer.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager
Crumbs User

Query parameters:

customerId - string
- The id of the customer to get notes for
startAt - number
- The note to start at

Input or request example:

customerId is an alphanumeric id, e.g. 61def792-3027-4a50-aa24-f31ecff83f6d
startAt is a non-negative number, e.g. 0

cURL:

200 - Array<Note>

Output or response example (e.g. 2 notes returned):

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

Create Note

POST /note

Create a note.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager

Body:

customerId - string
- The id of the customer to create the note for
body - string
- The text contents of the note

cURL:

200 - Note

Output or response example:

400

Returned if:

the request body is missing.
is missing required fields.
contains invalid field values.
is invalid for any other reason.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the customer is not found.

Update Note

PUT/note/{noteId}

Update a note.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager

Path parameters:

noteId - string
- The id of the note to update

Body:

body - string
- The text contents of the note

Input or request example:

noteId is an alphanumeric id, e.g. 61def792-3027-4a50-aa24-f31ecff83f6d

cURL:

200 - Note

Output or response example:

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the note is not found.

Delete Note

DELETE /note/{noteId}

Delete a note.

Permissions required, any of the following:

Crumbs Administrator
Crumbs Manager

Path parameters:

noteId - string
- The id of the note to delete

Input or request example:

noteId is an alphanumeric id, e.g. 61def792-3027-4a50-aa24-f31ecff83f6d

cURL:

200

Successful request will only return 200 with no other output.

401

Returned if the authentication credentials are incorrect or missing.

403

Returned if the user does not have the necessary Crumbs permission.

Returned if the user instance is not licensed.

404

Returned if the note is not found.

Types

All types are described as JSON documents.

Type	Schema	Example

Type	Schema	Example
Customer	Type: object Properties: `id` - string `fields` - Field Values
Field Values	Type: object Properties are the `id` of each field. Values depend on the type. Default fields: `name` - string `website` - string `description` - string `address` - string `region` - string `zipCode` - string `city` - string `country` - string `mainContact` - string - An `accountId` of a user in Jira. Additional properties for each user created field of type Field Value.
Field Value	Type: depends on field type Field type: `line` Value type: string Field type: `select`: `GET` - Select Field Option `PUT`/`POST` - string Array of `id` for each Select Field Option Field type: `multi-select`: Value type `GET` - Array<Select Field Option> `PUT`/`POST` - Array<string> Array of `id` for each Select Field Option Field type: `users` Value type: Array<string> Array of `accountId` Field type: `date-time-picker` Value type: string	`line` field type value: `select` field type value: `GET` `POST`/`PUT` `multi-select` field type value: `GET` `POST`/`PUT` `users` field type value: `date-time-picker` field type value:
Field	Type: object Properties: `id` - string `name` - string `type` - Field Type `custom` - boolean `configuration` - Field Configuration
Field Type	Type: string One of: `line` - for single line text `select` - for select list `multi-select` - for multi select `users` - for multi user picker `date-time-picker` - for date time picker `multi-line` - for multi line text `user` - for single user picker
Field Configuration	Type: object (properties depends on field type) Field type: `select` and `multi-select`, properties: `options` - Array<Select Field Option>
Select Field Option	Type: object Properties: `id` - string - A unique identifier for the option `value` - Value of the option
Issue Links	Type: object Properties: `customerIds` - Array<string> - `id` of customers linked to the issue.
Issue Link	Type: object Property: `customerId` - string - `id` of customer
Note	Type: object Properties: `id` - string - a unique id `author` - string - author account id `created` - number - date created in epoch time `updated` - number - date updated in epoch time `body` - string - content of the note

Crumbs for Jira

Crumbs REST API

API Base URL

API Tokens

Authentication

Authorization

API Resources

Customer `/customer`

Get Customers

Get Customer

Create Customer

Update Customer

Delete Customer

Field `/field`

Get Fields

Get Field

Issue Link `/issueLink`

Get Issue Links

Create issue Link

Delete Issue Link

Note `/note`

Get Notes

Create Note

Update Note

Delete Note

Types

Customer

Field Values

Field Value

Field

Field Type

Field Configuration

Select Field Option

Issue Links

Issue Link

Note

Crumbs REST API

API Base URL

API Tokens

Authentication

Authorization

API Resources

Customer /customer

Get Customers

Get Customer

Create Customer

Update Customer

Delete Customer

Field /field

Get Fields

Get Field

Issue Link /issueLink

Get Issue Links

Create issue Link

Delete Issue Link

Note /note

Get Notes

Create Note

Update Note

Delete Note

Types

Customer

Field Values

Field Value

Field

Field Type

Field Configuration

Select Field Option

Issue Links

Issue Link

Note

Customer `/customer`

Field `/field`

Issue Link `/issueLink`

Note `/note`