/
Crumbs REST API

Crumbs REST API

Owned by Victor Lee
Last updated: Oct 01, 2024
12 min read

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:

curl \ --request GET 'https://crumbs.newverve.scot/api/1/customer/75aaaeeb-c871-4d9e-904b-10e07a639103?fields=address,mainContact,name,eb7e4568-d283-4329-8805-d3b4c4983f1d' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090'

200 - Customer

Output or response example:

{ "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.

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:

curl \ --request POST 'https://crumbs.newverve.scot/api/1/customer' \ --header 'Authorization: Bearer 1c831a91-3559-475e-b4d4-39efd65b9d94' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "New Crumbs Customer", "website": "www.red.com" }'

201 - Customer

Output or response example:

{ "id": "2dc31a8f-b1f8-4225-b136-281c90020d93", "fields": { "name": "New Crumbs Customer", "website": "www.red.com" } }

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:

curl \ --request PUT 'https://crumbs.newverve.scot/api/1/customer/2dc31a8f-b1f8-4225-b136-281c90020d93' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090' \ --header 'Content-Type: application/json' \ --data-raw '{ "country": "New country", "website": "www.yellow.com" }'

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

Only removes data in Crumbs.

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:

curl \ --request DELETE 'https://crumbs.newverve.scot/api/1/customer/2dc31a8f-b1f8-4225-b136-281c90020d93' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090'

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:

curl \ --request DELETE 'https://crumbs.newverve.scot/api/1/field' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090'

200 - Array<Field>

Output or response example:

[     {         "id": "name",         "name": "Name",         "type": "line",         "custom": false     },     {         "id": "address",         "name": "Address",         "type": "multi-line",         "custom": false     },     {         "id": "city",         "name": "City",         "type": "line",         "custom": false     },     {         "id": "region",         "name": "Region / State",         "type": "line",         "custom": false     },     {         "id": "country",         "name": "Country",         "type": "line",         "custom": false     },     {         "id": "website",         "name": "Website",         "type": "line",         "custom": false     },     {         "id": "description",         "name": "Description",         "type": "multi-line",         "custom": false     },     {         "id": "zipCode",         "name": "Post / Zip Code",         "type": "line",         "custom": false     },     {         "id": "mainContact",         "name": "Main Contact",         "type": "user",         "custom": false     },     {         "id": "2b075e98-5126-47c0-96d0-15b6914c2b2a",         "name": "date",         "type": "date-time-picker",         "custom": true     },     {         "id": "46d10572-9213-46d0-b889-32b2f71c6eca",         "name": "multiselect",         "type": "multi-select",         "configuration": {             "options": [                 {                     "id": "faffdd65-db3c-412e-8f3b-e1fb5af3bc93",                     "value": "1"                 },                 {                     "id": "abb7bab8-5cbe-4642-b728-90107029b4d4",                     "value": "2"                 },                 {                     "id": "10ccce02-8cd1-40a9-9bb1-8f813c1b3fd9",                     "value": "3"                 }             ]         },         "custom": true     },     {         "id": "79698942-0ff1-418b-a892-d303a856fe76",         "name": "user",         "type": "users",         "custom": true     },     {         "id": "b7f62223-7a04-411e-a436-d06740d892ff",         "name": "text",         "type": "line",         "custom": true     },     {         "id": "eb7e4568-d283-4329-8805-d3b4c4983f1d",         "name": "select",         "type": "select",         "configuration": {             "options": [                 {                     "id": "43a5ef43-2208-40a4-b872-50ae019fced0",                     "value": "1"                 },                 {                     "id": "5f3682c3-5bfe-4350-8fd2-85cb25250ef5",                     "value": "2"                 },                 {                     "id": "e4118863-ff5b-47d6-b02a-6c49a5948a80",                     "value": "3"                 }             ]         },         "custom": true     } ]

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:

curl \ --request GET 'https://crumbs.newverve.scot/api/1/field/eb7e4568-d283-4329-8805-d3b4c4983f1d' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090'

200 - Field

Output or response example:

{     "id": "eb7e4568-d283-4329-8805-d3b4c4983f1d",     "name": "select",     "type": "select",     "configuration": {         "options": [             {                 "id": "43a5ef43-2208-40a4-b872-50ae019fced0",                 "value": "1"             },             {                 "id": "5f3682c3-5bfe-4350-8fd2-85cb25250ef5",                 "value": "2"             },             {                 "id": "e4118863-ff5b-47d6-b02a-6c49a5948a80",                 "value": "3"             }         ]     },     "custom": true }

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:

curl \ --request GET 'https://crumbs.newverve.scot/api/1/issueLink/GSP-118' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090'

200 - Issue Links

Output or response example:

{ "customerIds": [ "218", "120" ] }

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:

curl \ --request POST 'https://crumbs.newverve.scot/api/1/issueLink/GSP-118' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerId": "206" }'

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:

curl \ --request DELETE 'https://crumbs.newverve.scot/api/1/issueLink/GSP-118' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerId": "206" }'

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:

curl \ --request GET 'https://crumbs.newverve.scot/api/1/note?customerId=61def792-3027-4a50-aa24-f31ecff83f6d&startAt=0' \ --header 'Authorization: Bearer c5d6819d-348a-4eeb-8fb4-4a66e5f6e5cf'

200 - Array<Note>

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

[ { "id": "cdeacb9d-5116-40cd-91d6-f60c774242ab", "author": "712020:48a3274a-d2c6-434f-9d5c-0cddf86a2669", "body": "Example text", "created": 1692110997687 }, { "id": "d7603c3c-07e2-42d7-bf27-b0ef8ca247b1", "author": "712020:48a3274a-d2c6-434f-9d5c-0cddf86a2669", "body": "Example text 2", "created": 1692178694783 } ]

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:

curl \ --request POST 'https://crumbs.newverve.scot/api/1/note' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090' \ --header 'Content-Type: application/json' \ --data '{ "customerId": "61def792-3027-4a50-aa24-f31ecff83f6d", "body": "Lorem ipsum dolor sit amet." }'

200 - Note

Output or response example:

{ "id": "61def792-3027-4a50-aa24-f31ecff83f6d", "body": "Lorem ipsum dolor sit amet.", "created": 1692179162980, "author": "712020:48a3274a-d2c6-434f-9d5c-0cddf86a2669" }

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:

curl \ --request PUT 'https://crumbs.newverve.scot/api/1/note/61def792-3027-4a50-aa24-f31ecff83f6d' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090' \ --data '{ "body": "Text before was Example text and now is this." }'

200 - Note

Output or response example:

{ "id": "61def792-3027-4a50-aa24-f31ecff83f6d", "author": "712020:48a3274a-d2c6-434f-9d5c-0cddf86a2669", "body": "Text before was Example text and now is this.", "created": 1692110997687, "updated": 1692179408963 }

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:

curl \ --request DELETE 'https://crumbs.newverve.scot/api/1/note/61def792-3027-4a50-aa24-f31ecff83f6d' \ --header 'Authorization: Bearer 181e4e52-a646-4ce4-991d-a162621f3090'

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": "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", "fieldId-1": [ { "id": "optionId-1", "value": "Option 1" } ] } }

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.

{ "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", "fieldId-1": ["optionId-1"] }

Field Value

Type: depends on field type

line field type value:

"A value"

select field type value:

GET

{ "id": "optionId-1", "value": "Option 1" }

POST/PUT

"optionId-1"

multi-select field type value:

GET

[ { "id": "optionId-1", "value": "Option 1" }, { "id": "optionId-2", "value": "Option 2" } ]

POST/PUT

["optionId-1", "optionId-2"]

users field type value:

["accountId-1"]

date-time-picker field type value:

"2022-07-25T01:30+0100"

Field

Type: object

Properties:

{ "id": "field-a", "name": "A Field", "type": "select" "custom": true, "configuration": { "options": [ { "id": "optionId-1", "value": "Option 1" } ] } }

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

"text"

Field Configuration

Type: object (properties depends on field type)

{ "options": [ { "id": "optionId-1", "value": "Option 1" } ] }

Select Field Option

Type: object

Properties:

  • id - string - A unique identifier for the option

  • value - Value of the option

{ "id": "optionId-1", "value": "Option 1" }

Issue Links

Type: object

Properties:

  • customerIds - Array<string> - id of customers linked to the issue.

{ "customerIds": ["customerId-1", "customerId-2"] }

Issue Link

Type: object

Property:

  • customerId - string - id of customer

{ "customerId": "customerId-1" }

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

{ "id": "cdeacb9d-5116-40cd-91d6-f60c774242ab", "author": "712020:48a3274a-d2c6-434f-9d5c-0cddf86a2669", "body": "Example text", "created": 1692110997687, "updated": 1692110997690 }

 

 

Related content