Crumbs REST API

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

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:

  1. Create new tokens with a label.

  2. 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.

  3. View previously generated tokens by their label.

  4. View when the token was created.

  5. 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:

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

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:

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)

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