Allergens

Your allergens plus the shared NutraSoft reference set. Shared rows are read-only.

catalog:readcatalog:writehttps://public-api.nutrasoft.ca/v1

Linked fromProductsallergens[].allergen_id

The Allergen object

idinteger
Stable identifier for this allergen.
codestringnullable
Short code, unique within an account. Null on older rows.
descriptionstringnullable
Free text. Null when never filled in.
is_globalboolean
True for a NutraSoft-supplied reference row shared by every account, which your account can read but not change.
is_major_allergenboolean
Whether this is a major allergen for labelling purposes.
namestring
English name.
name_frstring
French name.
regulatory_referencestringnullable
The regulation this allergen is declared under, if recorded.

Operations

List allergens

get/allergenscatalog:read

Your account's allergens plus the shared reference rows, marked is_global. Use search or the named filters, not both.

Query parameters

searchstringnullable
Free-text match across name, code, description and regulatory reference.
namestringnullable
Partial match on either name.
codestringnullable
Partial match on the code.
descriptionstringnullable
Partial match.
regulatory_referencestringnullable
Partial match.
is_major_allergenbooleannullable
sortstringnullable
Comma-separated field:direction pairs, e.g. id:desc. Sortable: code, id, is_major_allergen, name, name_fr. id is always added last, so paging is stable.
limitinteger
Rows to return. Maximum 200.
- >= 1
- <= 200
- default 50
offsetinteger
Rows to skip. Maximum 10000: to read further, narrow the filters or page with updated_since.
- >= 0
- <= 10000
- default 0

Returns

200 A page of Allergen objects in data, with pagination.

Errors

400 401 403 429 500 503

GET /allergens

curl "https://public-api.nutrasoft.ca/v1/allergens?limit=50" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": [
    {
      "id": 123,
      "code": "SAMPLE-01",
      "description": "string",
      "is_global": false,
      "is_major_allergen": false,
      "name": "Sample name",
      "name_fr": "string",
      "regulatory_reference": "string"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 1,
    "has_more": false
  },
  "order": "id:asc"
}

Retrieve an allergen

get/allergens/{allergen_id}catalog:read

Path parameters

allergen_idintegerrequired
The allergen's id.
- > 0

Returns

200 One Allergen object in data.

Errors

400 401 403 404 429 500 503

GET /allergens/{allergen_id}

curl "https://public-api.nutrasoft.ca/v1/allergens/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "code": "SAMPLE-01",
    "description": "string",
    "is_global": false,
    "is_major_allergen": false,
    "name": "Sample name",
    "name_fr": "string",
    "regulatory_reference": "string"
  }
}

Create an allergen

post/allergenscatalog:write

Name and code are unique within your account; a duplicate is a 409.

Request body

namestringrequired
- min 1 chars
- max 100 chars
name_frstringrequired
- min 1 chars
- max 100 chars
codestringnullable
- max 40 chars
descriptionstringnullable
- max 500 chars
is_major_allergenboolean
- default false
regulatory_referencestringnullable
- max 50 chars

Returns

201 One Allergen object in data.

Errors

400 401 403 409 429 500 503

POST /allergens

curl -X POST "https://public-api.nutrasoft.ca/v1/allergens" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Sample name",
  "name_fr": "string"
}'

Response201

{
  "data": {
    "id": 123,
    "code": "SAMPLE-01",
    "description": "string",
    "is_global": false,
    "is_major_allergen": false,
    "name": "Sample name",
    "name_fr": "string",
    "regulatory_reference": "string"
  }
}

Update an allergen

patch/allergens/{allergen_id}catalog:write

Omitted fields are left unchanged. Shared rows are read-only (403).

Path parameters

allergen_idintegerrequired
The allergen's id.
- > 0

Request body

codestringnullable
- max 40 chars
descriptionstringnullable
- max 500 chars
is_major_allergenbooleannullable
namestringnullable
- min 1 chars
- max 100 chars
name_frstringnullable
- min 1 chars
- max 100 chars
regulatory_referencestringnullable
- max 50 chars

Returns

200 One Allergen object in data.

Errors

400 401 403 404 409 429 500 503

PATCH /allergens/{allergen_id}

curl -X PATCH "https://public-api.nutrasoft.ca/v1/allergens/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "code": "SAMPLE-01"
}'

Response200

{
  "data": {
    "id": 123,
    "code": "SAMPLE-01",
    "description": "string",
    "is_global": false,
    "is_major_allergen": false,
    "name": "Sample name",
    "name_fr": "string",
    "regulatory_reference": "string"
  }
}

Delete an allergen

delete/allergens/{allergen_id}catalog:write

Deletes one of your allergens. Refused with 409 while a product declares it. Shared rows are read-only (403).

Path parameters

allergen_idintegerrequired
The allergen's id.
- > 0

Returns

200 One Allergen object in data.

Errors

400 401 403 404 409 429 500 503

DELETE /allergens/{allergen_id}

curl -X DELETE "https://public-api.nutrasoft.ca/v1/allergens/123" \
  -H "Authorization: Bearer $NUTRASOFT_API_KEY"

Response200

{
  "data": {
    "id": 123,
    "code": "SAMPLE-01",
    "description": "string",
    "is_global": false,
    "is_major_allergen": false,
    "name": "Sample name",
    "name_fr": "string",
    "regulatory_reference": "string"
  }
}