AI-ready version:

List Available Allocations

Description

This API retrieves a list of all allocations for a specific company_id. It includes details such as allocation name, description, pricing, and additional metadata.

Endpoint

GET https://impact.dots.eco/api/v1/allocations?company_id={company_id}&langcode={langcode}

Refer to Headers and Authorization for detailed information about required headers and authentication.

Parameters

Name	Required	Type	Description
`company_id`	Yes	`integer`	The ID of the company for which allocations are to be retrieved.
`langcode`	No	`string`	Language code for the response. Defaults to English. See supported languages here.

Example Request

Minimal Request Example

curl --location --request GET 'https://impact.dots.eco/api/v1/allocations?company_id=1' \
--header 'Content-Type: application/json' \
--header 'auth-token: YOUR_AUTH_TOKEN'

Responses

Example Successful Response

A successful request returns a JSON object with details of the allocations for the specified company.

Response Body

{
  "2": {
    "allocation_name": "Allocation",
    "display_name": "Allocation display name",
    "allocation_id": "2",
    "allocation_description": "Allocation Description",
    "allocation_long_description": "Allocation long Description",
    "allocation_singular_label": "Allocation [qty] ft2 land",
    "allocation_plural_label": "Allocations [qty] ft2 land",
    "msrp_price": 0.5,
    "msrp_currency": "USD",
    "price_per_unit": {
      "number": "0.650000",
      "currency_code": "USD"
    },
    "allocation_image": "https://impact.dots.eco/sites/default/allocation_image.jpeg"
  }
}

Response Fields

Field	Type	Description
`allocation_name`	`string`	The name of the allocation.
`display_name`	`string`	A user-friendly display name for the allocation.
`allocation_id`	`string`	Unique identifier for the allocation.
`allocation_description`	`string`	Short description of the allocation.
`allocation_long_description`	`string`	Longer, detailed description of the allocation.
`allocation_singular_label`	`string`	Singular label to describe the allocation unit (e.g., "[qty] ft² land").
`allocation_plural_label`	`string`	Plural label for multiple allocation units.
`msrp_price`	`number`	Manufacturer Suggested Retail Price (MSRP) per unit.
`msrp_currency`	`string`	Currency for the MSRP price (e.g., `"USD"`).
`price_per_unit.number`	`number`	Price per unit of the allocation.
`price_per_unit.currency_code`	`string`	Currency code for the price per unit (e.g., `"USD"`).
`allocation_image`	`string`	URL of the allocation's associated image.

Errors

404 Not Found

This error occurs when the specified company_id is invalid or no allocations are associated with it.

Error Message	Cause
`"Invalid company id."`	The specified `company_id` does not exist or is invalid.
`"No results found for specified criteria."`	No allocations match the provided query parameters.

HTTP Status Code

Code	Description
404	No matching results for the request.

403 Access Denied

This error occurs when the request fails due to insufficient permissions to access allocations for the specified company.

Error Message	Cause
`"Access denied: you don't have permissions to see allocations of this company."`	User is not authorized to access allocations for the company.

HTTP Status Code

Code	Description
403	Access denied to the requested resource.

Notes

Mandatory Parameters: Ensure the company_id parameter is included for the request to execute successfully.
Default Language: If the langcode parameter is not specified, the response will default to English (en).

For more details, refer to the Headers and Authorization guide.