Positions

This section has operations to manage positions taken by investors in green assets, i.e. showing, adding, and removing positions

getPositions

Returns the investments in green assets by an investor

POST https://api.bws.ninja/v1/call

Use this operation to retrieve the investments of a particlar investor.

Request Body

Name	Type	Description
solution*	string	BWS.ESG.Credits
operation*	string	getPositions
parameters*	JSON	check Operation parameters

Example response

200: OK Successful operation (example)

[
    {
        "position_id": 6,
        "position_amount": 2400000,
        "position_currency_code": "EUR",
        "position_days": 180,
        "position_start_date": "2023-02-01",
        "investor_identifier": "3a6515809856",
        "investor_name": "John Smith",
        "asset_identifier": "XS24427682",
        "asset_name": "Asset X, 5-year",
        "issuer_identifier": "good-bank-issuer",
        "issuer_name": "Good Bank"
    },
    {
        "position_id": 16,
        "position_amount": 300000,
        "position_currency_code": "NOK",
        "position_days": 365,
        "position_start_date": "2023-01-01",
        "investor_identifier": "3a6515809856",
        "investor_name": "John Smith",
        "asset_identifier": "XS25798443",
        "asset_name": "Asset Y, 4-year",
        "issuer_identifier": "good-bank-issuer",
        "issuer_name": "Good Bank"
    }
]

400: Bad Request Error message (example)

{
    "message": "No such position(s) for that investor."
}

401: Unauthorized Error message

{
    "message": "Not authorized."
}

Operation parameters

Parameter	Type/Format	Required	Description
investor_identifier	string	yes	String identifier for an investor
asset_identifier	string	no	String identifier for a specified asset to include. Default is all.
issuer_identifier	string	no	String identifier for a specified issuer to include. Default is all.
user_identifier	string	no	For limiting the output to the investors that the user has access to
decryption_key	string	no	For decrypting personally identifiable information

Example code

curl

curl --location 'https://api.bws.ninja/v1/call' \
--header 'X-Api-Key: API-KEY' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.ESG.Credits",
    "operation": "getPositions",
    "parameters": {
        "investor_identifier": "9c809eb86ee6",
        "asset_identifier": "XS123456",
        "issuer_identifier": "good_issuer",
        "decryption_key": "64dh_WtAnyMK-f3dtb5-ESweLX80P__a3FjXsgg3Y="
        }
    }

addPosition

Creates and updates an investment in a green asset of an investor

POST https://api.bws.ninja/v1/call

Use this operation to register investments to a particular investor.

Request Body

Name	Type	Description
solution*	string	BWS.ESG.Credits
operation*	string	addPosition
parameters*	JSON	check Operation parameters

Example response

200: OK Successful operation (example)

{
    "message": "Existing position was successfully changed (id). 6"
}

400: Bad Request Error message (example)

{
    "message": "Reporting year is not available. Position is stored, but impact is not calculated."
}

401: Unauthorized Error message

{
    "message": "Not authorized."
}

Operation parameters

Parameter	Type/Format	Required	Description
investor_identifier	string	yes	String identifier for an investor
asset_identifier	string	yes	String identifier for an asset
position_amount	number/integer	yes	Amount of money invested
position_currency_code	string	yes	Currency code of the investment, as per getCurrencies
reporting_year	number/4 digits	no	Year of the taxonomy (if impact calculation is to be done at this stage)
position_days	number/integer	no	The term of the investment, default is 365 days (if impact calculation is to be done at this stage)
position_start_date	date/YYYY-MM-DD	no	Date of investment (for ESG Credits certificate generation)

Example code

curl

curl --location 'https://api.bws.ninja/v1/call' \
--header 'X-Api-Key: API-KEY' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.ESG.Credits",
    "operation": "addPosition",
    "parameters": {
        "investor_identifier": "9c809eb86ee6",
        "asset_identifier": "XS123456",
        "position_amount": 2500000,
        "position_currency_code": "EUR",
        "reporting_year": 2023,
        "position_days": 180,
        "position_start_date": "2023-02-01"
        }
    }

removePosition

Removes an investment in a green asset, and also its impact

POST https://api.bws.ninja/v1/call

Use this operation to remove an investment from a particular investor, where also any associated ESG impact records will be removed.

Request Body

Name	Type	Description
solution*	string	BWS.ESG.Credits
operation*	string	removePosition
parameters*	JSON	check Operation Parameters

Example response

200: OK Successful operation

{
    "Position was successfully removed"
}

400: Bad Request Error message (example)

{
    "message": "No such position."
}

401: Unauthorized Error message

{
    "message": "Not authorized."
}

Operation parameters

Parameter	Type/Format	Required	Description
investor_identifier	string	yes	String identifier for an investor
position_id	number/integer	yes	Integer identfier for an investment

Example code

curl

curl --location 'https://api.bws.ninja/v1/call' \
--header 'X-Api-Key: API-KEY' \
--header 'Content-Type: application/json' \
--data '{
    "solution": "BWS.ESG.Credits",
    "operation": "removePosition",
    "parameters": {
        "investor_identifier": "9c809eb86ee6",
        "position_id": 45
    }