Altruistiq Logo

Altruistiq Datasource API (1.0.0)

Download OpenAPI specification:

Definitions

An Activity is a business process that has taken place, which is relevant for emissions measurement. Examples of an Activity in Altruistiq’s data model are ElectricityUse or WasteGenerated. A Calculation Method is an GHG Protocol compliant method to calculate emissions from Activity data. Calculation Methods have a unique set of data requirements, but are not unique to an Activity. A Datasource is a single data format that your data is shared with Altruistiq in. Alongside this function, a Datasource plays the role of linking a data format to key contextual information (e.g. relevant Facilities, relevant Activities, owner, chosen Calculation Methods, status). Datasets are then individual files ingested via that Datasource. Each Dataset has a live status for full data lineage and transparency that you can track in the application.

Datasource API Outline

Primarily, Altruistiq’s Datasource API enables the creation and management of Datasources and the upload of new Datasets. Alongside this there are a number of supporting functions.

The Datasource API is governed by the oauth2 protocol.

The Datasource API by default does not expect sudden bursts of data upload (e.g. 25x5GB of data transferred at once), but instead delta datasets. When uploading to the upload endpoint the files uploaded must be chunked into chunks < 100mb and if there are more than 1 part then chunks must be > 5mb (the last part can be below this). If this is not the case for your business, do raise this at your Kick Off call and we will accommodate this.

PACT API Outline

Primarily, Altruistiq’s PACT API allows customers to export Product Carbon Footprint (PCF) data in a PACT conformant way. PACT is the Partnership for Carbon Transparency, a WRI and WBCSD funded NGO that is setting the calculation and technological standard for the exchange for Product Carbon Footprints between businesses. Today, Altruistiq is 1 of ~10 PACT conformant solutions globally.

The PACT API is is governed by the oauth2 protocol (see Security).

For full documentation of our PACT API, please go to https://wbcsd.github.io/data-exchange-protocol/v2/#api-examples. This provides the full documentation for product data exports, and the associated data model.

Security

The Altruistiq API uses TLS and follows the OAuth 2.0 Client credentials flow as per RFC 6749

Generating client_id and client_secret

In order to generate your client_id and client_secret, go to the altruistiq application’s organisation settings.

Retrieve an access token

Retrieve an access token which will enable access to private areas of the API

Authorizations:
oauth2
Request Body schema: application/x-www-form-urlencoded
client_id
required
string

The client ID.

client_secret
required
string

The client secret.

grant_type
required
string
Value: "client_credentials"

Responses

Request samples 

token_req_data = {
  'grant_type': 'client_credentials',
  'client_id': client_id,
  'client_secret': client_secret
}
token_response = requests.post(
  "https://app.altruistiq.com/api/public/v1/oauth2/token",
  data=token_req_data
)
token = token_response.json()['access_token']

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 4000
}

Datasource

Altruistiq’s datasource API enables you to:

  • Create new datasources
  • Manage existing datasources (read, update)
  • Upload data to a datasource

A datasource is the place where you will share a single data format with altruistiq and where you will categorise it so that we can calculate emissions in an automated way.

Start a multipart upload

Use this endpoint to start your multipart upload and retrieve an uploadId and fileId.

Authorizations:
bearerAuth
path Parameters
dataSourceId
required
string

ID of datasource

query Parameters
userEmail
required
string

Email of user initiating upload.

fileName
required
string

Name of file that is being uploaded.

Responses

Request samples 

const headers = {
    'Authorization': 'Bearer tokenId123',
    'Content-Type': 'application/json'
}

const response = await fetch(`https://app.altruistiq.com/api/public/v1/datasource/123/upload?fileName=testing.csv&userEmail=user@altruistiq.com`, {
  method: 'GET',
  headers: headers,
})

const multipartStartResponse = await response.json()

const results = {
  uploadId: multipartStartResponse.uploadId,
  fileId: multipartStartResponse.fileId
}

Response samples

Content type
application/json
{
  • "status": "Multipart Upload started",
  • "uploadId": "123",
  • "fileId": "123"
}

Upload a file to a datasource

Use this endpoint to upload your binary.

Authorizations:
bearerAuth
path Parameters
dataSourceId
required
string

ID of datasource

header Parameters
Content-Type
any
Example: multipart/form-data
Content-Range
any
Example: bytes 0-100/1000
Request Body schema: multipart/form-data
file
required
Array of strings <binary> [ items <binary > ]
uploadId
required
string
partNo
required
number

Responses

Request samples 

part = 1
parts = []
auth_headers = {'Authorization': 'Bearer ' + token}
for chunk in chunk_file(file_name):
    files = [
        ('file', (file_name, chunk, 'application/octet-stream')),
        ('uploadId', (None, upload_id)),
        ('partNo', (None, part))
    ]
    upload_response = requests.post(datasource_url, headers=auth_headers, files=files)
    upload_response_json = upload_response.json()
    parts.append(upload_response_json["parts"])
    part += 1

Response samples

Content type
application/json
{
  • "dataSourceId": "123",
  • "parts": [
    ],
  • "status": "Upload Complete"
}

Complete a multipart file upload

Use this endpoint to complete a file upload.

Authorizations:
bearerAuth
path Parameters
dataSourceId
required
string

ID of datasource

uploadId
required
string

ID of upload

fileId
required
string

ID of file

Request Body schema: application/json
fileName
string
parts
any <array>

Responses

Request samples

Content type
application/json
{
  • "fileName": "test.csv",
  • "parts": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "Multipart Upload Complete"
}

Export

Altruistiq’s Export API enables you to:

  • Export corporate data

Exporting data is a key part of the Altruistiq platform. It allows you to take your data and use it in other systems, or to share it with other stakeholders.

Currently, our Export API allows you to export your Corporate Emissions data available in Altruistiq, down to a daily grain. We are working hard to also add Product Emissions data to your Export API. If you need to share Product emissions data today, see the PACT API.

Schema of files which can be retrieved via this API (data dictionary):

ColumnData TypeFormatOptionalDescription
fact_uuid string uuid no Unique identifier for emission record.
calendar_date string date no Date of the emission record.
calendar_year integer no Year of the emission record.
emission_quantity number | string decimal(28, 10) no Quantity of the emission record.
emission_unit string no Unit the emissions are in.
calculation_input_quantity number | string | null decimal(28, 10) yes Input quantity used for the actual emission calculation (if applicable).
calculation_input_quantity_unit string | null yes Unit of the input quantity used for the actual emission calculation(if applicable).
spend_usd number | string | null decimal(28, 10) yes Spend in USD used for the actual emission calculation (if applicable).
spend_eur number | string | null decimal(28, 10) yes Spend in EUR used for the actual emission calculation (if applicable).
spend_gbp number | string | null decimal(28, 10) yes Spend in EUR used for the actual emission calculation (if applicable).
per_unit string no Emission Factor divisor.
input_dimensionality string no Dimensionality of the input quantity for the emission factor.
scope_category string no Scope categories are a subdivision of GHG Scopes with more detail about the emission’s cause. Scope categories are similar to, and overlapping with Activities.
scope string no Refers to the three scopes of the GHG Protocol.
activity_area_name string no Activity areas are groups of activities that have similar emissions calculation methodologies in the Altruistiq platform.
activity_name string no Activities areas are activities of a customer causing emissions.
sub_activity_name string no Sub-Activities areas are a sub-dicision activities of a customer causing emissions.
aq_calc_method string no Calculation Methodology used in the Altruistiq platform.
ghg_calc_method string no Calculation Methodology according to the GHG protocol.
ef_specificity string no Specificity level that Emission Factors refer to, e.g. Global Average or Country Average.
accuracy_score integer no A measure of how accurate emissions calculations are for a particular activity, based on the quality of data available and the calculation methodology applied as a result.
accuracy_score_name string no A measure of how accurate emissions calculations are for a particular activity, based on the quality of data available and the calculation methodology applied as a result.
lifecycle string no Emissions caused by an activity can be further subdivided by the lifecycle they are associated with. For example, a business trip in a company car will cause emissions from vehicle use (i.e. burning the fuel) and well-to-tank emissions (i.e. drilling for oil, fuel production, and any other activities in the supply chain).
bu_uuid string uuid no Unique identifier for a BU.
bu_name string no Name of the BU this record belongs to.
root_org_uuid string uuid no Unique identifier of the root organisation.
root_org_name string no Name of the root organisation this record belongs to.
facility_name string | null yes Name of the facility this record belongs to (if it is assigned at facility level).
facility_uuid string | null yes Unique identifier of the facility.
facility_country_name string | null yes Country this facility belongs to.
facility_country_code string | null yes Country code of the country this facility belongs to.
facility_post_code string | null yes Post code of this facility.
facility_type string | null yes Type of this facility.
facility_capacity_ratio number | string | null decimal(28, 10) yes Capacity of this facility.
data_source_name string yes Name of the datasource which was used for this record.
file_name string no Name of the file which was used for this record.
supplier_legal_name string | null yes Supplier legal name (if applicable).
supplier_country_code string | null yes Supplier country code (if applicable).
supplier_country_name string | null yes Supplier country name (if applicable).
supplier_vat_number string | null yes Supplier VAT number (if applicable).
tags object no Mapping of tag category -> value (e.g. energy_type -> mixed).

PREVIEW WARNING: THESE ARE CURRENTLY BEING CHANGED, SO ARE NOT STABLE!

Categories:

  • energy_type
  • fuel_type
  • fuel_net_or_gross_cv
  • gas_type
  • isic_section
  • isic_division
  • isic_group
  • isic_class
  • goods_service_type
  • material_life_phase
  • heating_type
  • industry_type
  • purchased_energy_type
  • refrigerant_type
  • renewable
  • vehicle_type
  • journey_type
  • energy_generation_type
  • vehicle_emission_type
  • traffic_scenario
  • vehicle_load
  • waste_category
  • wastewater_spend_type
  • waste_treatment_type
  • waste_type
  • water_spend_type
financial_year integer no
custom_analytics_fields object no Custom Analytics Fields.
custom_tags object no Fields used to tag/classify the record.
emission_factor_name string | null no Name of the emission factor used for this record.
emission_factor_specificity string | null no Specificity of the emission factor used for this record.
emission_factor_specificity_code string | null no Specificity Code of the emission factor used for this record.
emission_factor_source string | null no Source of the emission factor used for this record.
emission_factor_source_version string | null no Source version of the emission factor used for this record.
created_at string date-time no Timestamp when the record was created. NOTE: this might change if we do a full refresh in the backend.
updated_at string date-time no Timestamp when the record was updated. NOTE: this might change if we do a full refresh in the backend.

Create an Export

Use this endpoint to create and start an export.

Authorizations:
bearerAuth
Request Body schema: application/json
required
object
required
object

Responses

Request samples

Content type
application/json
{
  • "format": {
    },
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "status": "QUEUED",
  • "exportId": "3f0b7fbd-fa45-445a-8862-49cd1871eebc"
}

Get export status and download urls

Poll this endpoint to retrieve download URLs and the status of an export.

Authorizations:
bearerAuth

Responses

Request samples 

# needs export_id from GET /api/public/v1/export
# needs token from /api/public/v1/oauth2/token

import requests
from time import sleep
# if using pandas also
import pandas as pd


def wait_for_success(export_id: str):
  while True:
    response = requests.get(
      f"https://app.altruistiq.com/api/public/v1/export/{export_id}",
      headers={
        "Authorization": f"Bearer {token}"
      }
    )
    response.raise_for_status()
    export = response.json()
    status = export["status"]
    if status in {"FAILED", "CANCELLED"}:
      raise RuntimeError(f"Failed export {export}.")
    if status == "SUCCEEDED":
      break
    sleep(5.0)
  return export

export = wait_for_success(export_id)
for i, url in enumerate(export["urls"]):
  file_download = requests.get(url)
  file_download.raise_for_status()
  file_type = export['format']['type'].lower()
  compression = export['format'].get('compression', 'gz')
  with open(f"my_folder/file_{i}.{file_type}.{compression}", "w") as f:
    f.write(file_download.content)

# alternatively if using pandas and you specified parquet format - this assumes data fits into memory
pd.concat((pd.read_parquet(url) for url in export["urls"]))

Response samples

Content type
application/json
{}

Product

Altruistiq’s Product API enables you to:

  • Create new products
  • Update existing products
  • Delete products
  • Get a list of products
  • All the above in bulk

Create a single product

Use this endpoint to create a single product record.

Authorizations:
bearerAuth
Request Body schema: application/json
required

CreateProductRequest

productKey
required
string

Your product code or identifier.

name
required
string

The name of the product

description
string

The description of the product.

category
string

The category the product falls into.

declaredUnit
required
string

A single declared unit of the product.

weightPerDeclaredUnit
required
number > 0

Weight of a single declared unit

weightUnit
required
string
Enum: "g" "kg" "kt" "lb" "long_ton" "oz" "short_ton" "t"

The weight unit of the declared unit weight

additionalData
object

Additional JSON data for the product

Responses

Request samples

Content type
application/json
{
  • "productKey": "CAN-1234A",
  • "name": "Canned food - Single",
  • "description": "Our best ever canned food product",
  • "category": "Food",
  • "declaredUnit": "1 can",
  • "weightPerDeclaredUnit": "100",
  • "weightUnit": "kg",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "aee349fd-28e4-450d-9e20-af64d9c0d813"
}

Get products in bulk

Use this endpoint to retrieve information about multiple products

Authorizations:
bearerAuth
query Parameters
query
string
Example: query=example search string

A search string to filter records by

perPage
number [ 1 .. 500 ]
Example: perPage=10

The number of records to return in the response

pageNo
number >= 1
Example: pageNo=1

The paginated page number of records to return

sortOrder
string
Enum: "ASC" "DESC"
Example: sortOrder=ASC

Ordering of the results, Ascending or Descending

sortField
string
Enum: "name" "description" "category" "declared_unit" "declared_unit_weight" "created_at" "updated_at" "product_key"
Example: sortField=name

The field name to sort the records on

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update products in bulk

Use this endpoint to update multiple products at the same time.

Authorizations:
bearerAuth
Request Body schema: application/json
required

BulkUpdateProductsRequest

required
Array of objects (UpdateProductBase)

Array of products to update

Responses

Request samples

Content type
application/json
{
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete products in bulk

Use this endpoint to delete multiple products at the same time.

Authorizations:
bearerAuth
Request Body schema: application/json
required

BulkDeleteProductsRequest

ids
required
Array of strings <uuid> non-empty [ items <uuid > ]

An array of product UUIDs

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Get a single product

Use this endpoint to retrieve information about a single product

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "id": "aee349fd-28e4-450d-9e20-af64d9c0d813",
  • "productKey": "CAN-1234A",
  • "name": "Canned food - Single",
  • "description": "Our best ever canned food product",
  • "category": "Food",
  • "declaredUnit": "1 can",
  • "weightPerDeclaredUnit": "100",
  • "weightUnit": "kg",
  • "updatedAt": "2025-01-01",
  • "additionalData": {
    }
}

Update a single product

Use this endpoint to update a single product record.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?
Request Body schema: application/json
required

UpdateProductRequest

id
required
string <uuid>

The UUID of the product record

name
string

The name of the product

description
string

The description of the product.

category
string

The category the product falls into.

declaredUnit
string

A single declared unit of the product.

weightPerDeclaredUnit
number > 0

Weight of a single declared unit

weightUnit
string
Enum: "g" "kg" "kt" "lb" "long_ton" "oz" "short_ton" "t"

The weight unit of the declared unit weight

additionalData
object

Additional JSON data for the product

Responses

Request samples

Content type
application/json
{
  • "id": "aee349fd-28e4-450d-9e20-af64d9c0d813",
  • "name": "Canned food - Single",
  • "description": "Our best ever canned food product",
  • "category": "Food",
  • "declaredUnit": "1 can",
  • "weightPerDeclaredUnit": "100",
  • "weightUnit": "kg",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete a single product

Use this endpoint to delete a single product record. When deleting a product, all related structures and inputs will also be deleted.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Create products in bulk

Use this endpoint to create multiple products at the same time.

Authorizations:
bearerAuth
Request Body schema: application/json
required

BulkCreateProductsRequest

required
Array of objects (CreateProductBase)

Array of products to create

Responses

Request samples

Content type
application/json
{
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Product structure

Altruistiq’s Product Structure API enables you to:

  • Create new product structures
  • Update existing product structures
  • Delete product structures
  • Get a list of all product structures
  • All the above in bulk against a single product

The product structure bulk actions are useful for creating and updating product structures in bulk. These structures are managed under the context of a single product, so require the product UUID to be provided in the request.

Create single product structures

Product structures represent a single production structure or BOM of a product. Create the structure record in order to add inputs for packaging and materials. Each structure is uniquely identified by customerStructureId — if none is supplied, the server derives one from the product, facility and validFrom date, so only one structure can exist per (product, facility, date) combination unless you provide your own unique customerStructureId.

Authorizations:
bearerAuth
Request Body schema: application/json
required

CreateProductStructureRequest

productId
required
string <uuid>

The UUID of the product record

validFrom
required
string\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d....

The date for which the structure was first used. Date-only granularity — any time component is discarded (e.g. 2025-01-01T14:30:00Z is stored as 2025-01-01).

facilityName
required
string

The name of the facility in which the product structure is manufactured.

routeDescription
string

A text string describing the route a product takes through the supply chain

customerStructureId
string

(Optional) Structure ID if you have your own generated identifiers for structures. Must be globally unique across all your product structures — the same customerStructureId cannot be reused for a different product, facility or date.

Responses

Request samples

Content type
application/json
{
  • "productId": "aee349fd-28e4-450d-9e20-af64d9c0d813",
  • "validFrom": "2025-01-01",
  • "facilityName": "Large factory",
  • "routeDescription": "New York > Paris > Munich",
  • "customerStructureId": "STRUC-001-ABC"
}

Response samples

Content type
application/json
{
  • "id": "52f78ded-ccad-4d8f-b474-29a4f6181e50"
}

Get single product structure

Return details for a single product structure, without its related inputs.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "id": "84400bd6-ceaf-4f79-9595-4e2f2b9782c5",
  • "productId": "aee349fd-28e4-450d-9e20-af64d9c0d813",
  • "facilityId": "6a99a4d5-a126-4fcd-93f4-1ca7c6a219b6",
  • "facilityName": "Large factory",
  • "validFrom": "2025-01-01",
  • "customerStructureId": "STRUC-001-ABC",
  • "routeDescription": "New York > Paris > Munich",
  • "createdAt": "2025-01-01",
  • "updatedAt": "2025-01-01"
}

Update a single product structure

The endpoint allows the updating of editable fields in product structure records. Product ID, facility and valid from dates are not editable in this endpoint. If those need updating, create a new structure record.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?
Request Body schema: application/json
required

UpdateProductStructureBody

routeDescription
required
string

A text string describing the route a product takes through the supply chain

Responses

Request samples

Content type
application/json
{
  • "routeDescription": "New York > Paris > Munich"
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete a single product structure

Use this endpoint to delete a single product structure. When deleting a product structure, all related inputs will also be deleted.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Creates product structures in bulk within a single product

Use this endpoint to create multiple product structures for a single product in one call. Each structure is uniquely identified by customerStructureId — if none is supplied, the server derives one from the product, facility and validFrom date, so only one structure can exist per (product, facility, date) combination unless you provide your own unique customerStructureId.

Authorizations:
bearerAuth
path Parameters
productId
required
string[^\/#\?]+?
Request Body schema: application/json
required

CreateProductStructureRequest

productId
required
string <uuid>

The UUID of the product record

validFrom
required
string\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d....

The date for which the structure was first used. Date-only granularity — any time component is discarded (e.g. 2025-01-01T14:30:00Z is stored as 2025-01-01).

facilityName
required
string

The name of the facility in which the product structure is manufactured.

routeDescription
string

A text string describing the route a product takes through the supply chain

customerStructureId
string

(Optional) Structure ID if you have your own generated identifiers for structures. Must be globally unique across all your product structures — the same customerStructureId cannot be reused for a different product, facility or date.

Responses

Request samples

Content type
application/json
{
  • "productId": "aee349fd-28e4-450d-9e20-af64d9c0d813",
  • "validFrom": "2025-01-01",
  • "facilityName": "Large factory",
  • "routeDescription": "New York > Paris > Munich",
  • "customerStructureId": "STRUC-001-ABC"
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Get multiple product structure within a single product

Return details for multiple product structures within a single product.

Authorizations:
bearerAuth
path Parameters
productId
required
string[^\/#\?]+?
query Parameters
search
string
Example: search=example search string

A search string to filter records by

sortOrder
string
Enum: "ASC" "DESC"
Example: sortOrder=ASC

Ordering of the results, Ascending or Descending

sortField
string
Enum: "customerStructureId" "validFromDate" "facilityName" "routeDescription" "createdAt" "updatedAt"
Example: sortField=name

The field name to sort the records on

perPage
number [ 1 .. 500 ]
Example: perPage=10

The number of records to return in the response

pageNo
number >= 0
Example: pageNo=1

The paginated page number of records to return

Responses

Response samples

Content type
application/json
{
  • "structures": [
    ]
}

Update product structures in bulk within a single product

Use this endpoint to update multiple product structures for a single product in one call. Currently the only editable field is route description

Authorizations:
bearerAuth
path Parameters
productId
required
string[^\/#\?]+?
Request Body schema: application/json
required

BulkUpdateProductStructuresBody

required
Array of objects (UpdateProductStructureItem) non-empty

Array of structures to update

Responses

Request samples

Content type
application/json
{
  • "structures": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Deletes product structures in bulk within a single product

Use this endpoint to delete multiple product structures. When deleting a product structure, all related inputs will also be deleted.

Authorizations:
bearerAuth
path Parameters
productId
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Product structure inputs

Altruistiq’s Product Structure API enables you to:

  • Create new product structure inputs
  • Update existing product structure inputs
  • Delete product structure inputs
  • Get a list of all product structure inputs
  • All the above in bulk against a single product structure

The product structure input bulk actions are useful for creating and updating product structure inputs in bulk. These inputs are managed under the context of a single product, so require the product UUID to be provided in the request.

Create a single product structure input

Use this endpoint to create a single product structure input record.

Authorizations:
bearerAuth
Request Body schema: application/json
required

CreateProductStructureInputQuery

inputCode
string

Your identifier for the input.

inputName
required
string

The descriptive name of the input

inputCategory
string

A category for the input

inputSubCategory
string

A sub-category for the input

sourceCountry
string = 2 characters

The 2 character country code (ISO 3166-1 alpha-2) for the source country of the input

supplierName
string

The name of the supplier that the input is purchased from

supplierCountryCode
string = 2 characters

The 2 character country code (ISO 3166-1 alpha-2) for the location of the supplier of the input.

productOrPackaging
required
string
Enum: "PRODUCT" "PACKAGING"

Wheter the input is a product or packaging type

weight
required
number > 0

The weight of the input in one declared unit

weightUnit
required
string

The unit of weight for the input

recyclePercentage
number

How much of the input comes from recycled content

additionalData
any

Additional JSON data for the product

Responses

Request samples

Content type
application/json
{
  • "inputCode": "INPUT-001",
  • "inputName": "Tin sheet",
  • "inputCategory": "Metals",
  • "inputSubCategory": "Soft metals",
  • "sourceCountry": "GB",
  • "supplierName": "Metal Suppliers Ltd",
  • "supplierCountryCode": "GB",
  • "productOrPackaging": "PACKAGING",
  • "weight": "100",
  • "weightUnit": "g",
  • "recyclePercentage": "50",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "id": "84400bd6-ceaf-4f79-9595-4e2f2b9782c5"
}

Get a single product structure input

Use this endpoint to retrieve information about a single product structure input

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "id": "84400bd6-ceaf-4f79-9595-4e2f2b9782c5",
  • "structureId": "84400bd6-ceaf-4f79-9595-4e2f2b9782c5",
  • "inputCode": "INPUT-001",
  • "inputName": "Tin sheet",
  • "inputCategory": "Metals",
  • "inputSubCategory": "Soft metals",
  • "sourceCountry": "GB",
  • "supplierName": "Metal Suppliers Ltd",
  • "supplierCountryCode": "GB",
  • "productOrPackaging": "PACKAGING",
  • "weight": "100",
  • "weightUnit": "g",
  • "recyclePercentage": "50",
  • "createdAt": "2025-01-01",
  • "updatedAt": "2025-01-01",
  • "additionalData": {
    }
}

Update a single product structure input

Use this endpoint to update a single product structure input record.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?
Request Body schema: application/json
required

UpdateProductStructureInputBody

id
required
string <uuid>

The UUID of the structure input record

inputCode
string

Your identifier for the input.

inputName
string

The descriptive name of the input

inputCategory
string

A category for the input

inputSubCategory
string

A sub-category for the input

sourceCountry
string = 2 characters

The 2 character country code (ISO 3166-1 alpha-2) for the source country of the input

supplierName
string

The name of the supplier that the input is purchased from

supplierCountryCode
string = 2 characters

The 2 character country code (ISO 3166-1 alpha-2) for the location of the supplier of the input.

productOrPackaging
string
Enum: "PRODUCT" "PACKAGING"

Wheter the input is a product or packaging type

weight
number > 0

The weight of the input in one declared unit

weightUnit
string

The unit of weight for the input

recyclePercentage
number

How much of the input comes from recycled content

additionalData
object

Additional JSON data for the product

Responses

Request samples

Content type
application/json
{
  • "id": "84400bd6-ceaf-4f79-9595-4e2f2b9782c5",
  • "inputCode": "INPUT-001",
  • "inputName": "Tin sheet",
  • "inputCategory": "Metals",
  • "inputSubCategory": "Soft metals",
  • "sourceCountry": "GB",
  • "supplierName": "Metal Suppliers Ltd",
  • "supplierCountryCode": "GB",
  • "productOrPackaging": "PACKAGING",
  • "weight": "100",
  • "weightUnit": "g",
  • "recyclePercentage": "50",
  • "additionalData": {
    }
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete a single product structure input

Use this endpoint to delete a single product structure input record.

Authorizations:
bearerAuth
path Parameters
id
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Create product structure inputs in bulk within a single structure

Use this endpoint to create multiple product structure inputs for a single structure at the same time.

Authorizations:
bearerAuth
path Parameters
structureId
required
string[^\/#\?]+?
Request Body schema: application/json
required

BulkCreateProductStructuresInputsBody

required
Array of objects (CreateProductStructureInputs) non-empty

Array of product structure inputs to create

Responses

Request samples

Content type
application/json
{
  • "inputs": [
    ]
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Get product structure inputs in bulk within a single structure

Use this endpoint to retrieve information about multiple products structure inputs

Authorizations:
bearerAuth
path Parameters
structureId
required
string[^\/#\?]+?
query Parameters
search
string
Example: search=example search string

A search string to filter records by

perPage
number <= 500
Example: perPage=10

The number of records to return in the response

pageNo
number
Example: pageNo=1

The paginated page number of records to return

sortOrder
string
Enum: "ASC" "DESC"
Example: sortOrder=ASC

Ordering of the results, Ascending or Descending

sortField
string
Enum: "input_code" "product_structure_id" "input_name" "input_category" "product_or_packaging" "weight" "supplier_name" "created_at" "updated_at"
Example: sortField=name

The field name to sort the records on

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update product structure inputs in bulk within a single structure

Use this endpoint to update multiple product structure inputs at the same time.

Authorizations:
bearerAuth
path Parameters
structureId
required
string[^\/#\?]+?
Request Body schema: application/json
required

BulkUpdateProductStructureInputsRequest

required
Array of objects (ProductStructureInput) [ 1 .. 500 ] items

Array of product structure inputs to update

Responses

Request samples

Content type
application/json
{
  • "inputs": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true
}

Delete inputs in bulk within a single structure

Use this endpoint to delete multiple inputs at the same time.

Authorizations:
bearerAuth
path Parameters
structureId
required
string[^\/#\?]+?
Request Body schema: application/json
required

BulkDeleteProductStructureInputsBody

ids
required
Array of strings <uuid> non-empty [ items <uuid > ]

An array of input UUIDs

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Create product structure inputs in bulk for any structure

Use this endpoint to create multiple product structure inputs for any structure ID.

Authorizations:
bearerAuth
Request Body schema: application/json
required

BulkCreateProductInputsBody

required
Array of objects (CreateProductInputs) [ 1 .. 1000 ] items

Array of product structure inputs to create

Responses

Request samples

Content type
application/json
{
  • "inputs": [
    ]
}

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

Facility

Altruistiq's Facility API enables you to:

  • Create new facilities in bulk
  • Update existing facility persistent properties
  • Update facility version
  • Create new facility version
  • Delete facility versions
  • Delete facility
  • Get a list of facilities
  • Get a single facility

The facility API provides comprehensive management of facility data including location, capacity, and organizational structure.

Get a list of facilities

Retrieve a paginated list of facilities with optional filtering and sorting.

Authorizations:
bearerAuth
query Parameters
search
string
Example: search=example search string

A search string to filter records by

pageSize
number <= 1000
Example: pageSize=10

The number of records to return in the response

pageNo
number >= 1
Example: pageNo=1

The paginated page number of records to return

buId
string <uuid>
Example: buId=dff8f526-4c6a-4ea5-b740-4762aac04699

The UUID of the business unit

showClosed
boolean
Example: showClosed=false

Whether to include closed facilities in the results

sortBy
string
Enum: "facilityName" "internalId" "organization" "country"
Example: sortBy=facilityName

The field name to sort the records on

sortOrder
string
Enum: "ASC" "DESC"
Example: sortOrder=ASC

Ordering of the results, Ascending or Descending

Responses

Response samples

Content type
application/json
{
  • "facilities": [
    ]
}

Get a single facility

Retrieve detailed information about a specific facility.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...

Responses

Response samples

Content type
application/json
{
  • "facility": {
    }
}

Delete a facility

Delete an entire facility and all its versions.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...

Responses

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Get a specific facility version

Retrieve detailed information about a specific version of a facility.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[^\/#\?]+?
versionId
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "facility": {
    }
}

Delete a facility version

Delete a specific version of a facility.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...
versionId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...

Responses

Response samples

Content type
application/json
{
  • "message": "Not authorized"
}

Update a facility version

Update properties of a specific facility version.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...
versionId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...
Request Body schema: application/json
required

UpdatableFacilityVersionDTO

buId
required
string <uuid>

The UUID of the business unit

name
required
string

The name of the facility

hasAddress
required
boolean

Whether the facility has an address

addressLine1
string

First line of the facility address

addressLine2
string

Second line of the facility address

postalCode
string

Postal code of the facility

city
string non-empty

City where the facility is located

country
string

Country where the facility is located (ISO 3166-1 alpha-2)

countrySub
string non-empty

Subdivision of the country where the facility is located

capacity
number >= 0

Capacity of the facility

employeeCount
integer >= 0

Number of employees at the facility

boundaryIndicator
string
Enum: "OPERATIONAL_CONTROL" "SUPPLIER" "UPSTREAM_TRANSPORT_AND_DISTRIBUTION" "UPSTREAM_LEASED" "DOWNSTREAM_TRANSPORT_AND_DISTRIBUTION" "PROCESSING_OF_SOLD_PRODUCTS" "DOWNSTREAM_LEASED" "FRANCHISE" "INVESTMENT"

The boundary indicator for the facility

isOpen
boolean

Whether the facility is currently open

effectiveDate
string\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d....

Date when this facility version becomes effective

Responses

Request samples

Content type
application/json
{
  • "buId": "dff8f526-4c6a-4ea5-b740-4762aac04699",
  • "name": "Large Factory",
  • "hasAddress": true,
  • "addressLine1": "123 Main Street",
  • "addressLine2": "Suite 100",
  • "postalCode": "12345",
  • "city": "New York",
  • "country": "US",
  • "countrySub": "US-NY",
  • "capacity": 1000,
  • "employeeCount": 150,
  • "boundaryIndicator": "OPERATIONAL_CONTROL",
  • "isOpen": true,
  • "effectiveDate": "2025-01-01"
}

Response samples

Content type
application/json
{
  • "message": "Bad request"
}

Create multiple facilities in bulk

Create multiple facilities in a single request.

Authorizations:
bearerAuth
Request Body schema: application/json
required

FacilityBulkPublicDto

required
Array of objects (FacilityPublic) non-empty

Array of facilities to create

Responses

Request samples

Content type
application/json
{
  • "facilities": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Bad request"
}

Update facility persistent properties

Update persistent properties of a facility such as tags, internal ID, and facility type.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...
Request Body schema: application/json
required

FacilityPublicPersistentUpdateDTO

facilityId
required
string <uuid>

The UUID of the facility record

internalId
string

Your internal identifier for the facility

tags
Array of strings

Array of tags associated with the facility

facilityTypeId
string <uuid>

The UUID of the facility type

Responses

Request samples

Content type
application/json
{
  • "facilityId": "aee349fd-28e4-450d-9e20-af64d9c0d813",
  • "internalId": "FAC-001",
  • "tags": [
    ],
  • "facilityTypeId": "cff8f526-4c6a-4ea5-b740-4762aac04698"
}

Response samples

Content type
application/json
{
  • "message": "Bad request"
}

Create a new facility version

Create a new version of an existing facility.

Authorizations:
bearerAuth
path Parameters
facilityId
required
string[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-...
Request Body schema: application/json
required

CreateFacilityVersionDTO

effectiveDate
required
string\d{4}-[01]\d-[0-3]\dT[0-2]\d:[0-5]\d:[0-5]\d....

Date when this facility version becomes effective

buId
required
string <uuid>

The UUID of the business unit

name
required
string

The name of the facility

parentId
string <uuid>

The UUID of the parent facility

inheritParentAddress
boolean

Whether to inherit address from parent facility

hasAddress
required
boolean

Whether the facility has an address

addressLine1
string

First line of the facility address

addressLine2
string

Second line of the facility address

postalCode
string

Postal code of the facility

city
string non-empty

City where the facility is located

region
string

Region/state where the facility is located

country
string

Country where the facility is located (ISO 3166-1 alpha-2)

countrySub
string non-empty

Subdivision of the country where the facility is located

capacity
number >= 0

Capacity of the facility

employeeCount
integer >= 0

Number of employees at the facility

boundaryIndicator
string
Enum: "OPERATIONAL_CONTROL" "SUPPLIER" "UPSTREAM_TRANSPORT_AND_DISTRIBUTION" "UPSTREAM_LEASED" "DOWNSTREAM_TRANSPORT_AND_DISTRIBUTION" "PROCESSING_OF_SOLD_PRODUCTS" "DOWNSTREAM_LEASED" "FRANCHISE" "INVESTMENT"

The boundary indicator for the facility

isOpen
boolean

Whether the facility is currently open

Responses

Request samples

Content type
application/json
{
  • "effectiveDate": "2025-01-01",
  • "buId": "465ada2c-de62-48b9-97aa-f63bac84d323",
  • "name": "Large Factory 232",
  • "inheritParentAddress": false,
  • "hasAddress": true,
  • "addressLine1": "123 Main Street",
  • "addressLine2": "Suite 100",
  • "postalCode": "12345",
  • "city": "New York",
  • "ownershipType": "standalone_tracked",
  • "country": "US",
  • "countrySub": "US-NY",
  • "boundaryIndicator": "OPERATIONAL_CONTROL",
  • "isOpen": true
}

Response samples

Content type
application/json
{
  • "message": "Bad request"
}

Get facility types

Retrieve a list of facility types available for the organization, including both generic and organization-specific types.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "types": [
    ]
}

Location

Altruistiq's Location API enables you to:

  • Get a list of countries with their alpha_2 codes and names
  • Get country subdivisions for a specific country by its alpha-2 code

Get a list of countries

Retrieve a list of countries with their alpha_2 codes and names.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "countries": [
    ]
}

Get country subdivisions by country code

Retrieve a list of country subdivisions for a specific country by its alpha-2 code.

Authorizations:
bearerAuth
path Parameters
countryCode
required
string[^\/#\?]+?

Responses

Response samples

Content type
application/json
{
  • "subdivisions": [
    ]
}

Organization

Altruistiq's Organization API enables you to:

  • Get organization details and business units

The organization API provides access to organizational structure data including the root organization and its business units.

Get organization and business units

Retrieve all organizations including the root organization and its business units (id and name).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "organizations": [
    ]
}