Utilizing GUIDs

Working with APIs that use GUIDs (Globally Unique Identifiers) as path parameters can be powerful—but only if used correctly. In VaultN’s API, endpoints often require GUIDs to specify connections, price lists, or promotions. Understanding how to correctly format your requests and pass the right parameters ensures you receive the intended data without errors like 400 Bad Request or 404 Not Found.

In this guide, we’ll break down how to use GUIDs effectively in your API requests and how to correctly pass additional parameters like pagination to get precise results.

GUIDs uniquely identify resources in the VaultN ecosystem. The API uses GUIDs for:
• Connections: Represents the link between vaults.
• Price Lists: A specific set of prices shared or owned.
• Products/Promotions: Specific product instances or promotions.

Example GUID: a1b2c3d4-e5f6-7890-abcd-1234567890ef

1. Retrieve All Connections

Endpoint

GET https://sbx-api.vaultn.com/api/v2/connection

Description

Fetches all connections in your VaultN network. Each connection includes a unique guid used for future requests.

Example Response

[
  {
    "guid": "a1b2c3d4-e5f6-7890-abcd-1234567890ef",
    "created": "2024-01-01T12:00:00Z",
    "catalogSharingEnabled": true,
    "connectedOwner": {
      "name": "Partner Vault"
    }
  }
]

2. Retrieve Price Lists by Connection GUID

Endpoint

GET https://sbx-api.vaultn.com/api/v2/connection/{connectionGuid}/pricelist

Description

Retrieves price lists shared with a specific connection. Replace {connectionGuid} with a valid GUID from your connection list.

Example Request

GET https://sbx-api.vaultn.com/api/v2/connection/a1b2c3d4-e5f6-7890-abcd-1234567890ef/pricelist

Example Response

[
  {
    "id": 101,
    "guid": "987f6bcd-1234-5678-abcd-12345678abcd",
    "title": "Standard Price List",
    "type": 1,
    "created": "2024-01-10T10:00:00Z",
    "isDefault": true,
    "owned": "Shared",
    "connectionName": "Partner Vault",
    "typeName": "SalesPrice"
  }
]

3. Retrieve Prices with Parameters

Endpoint

GET https://sbx-api.vaultn.com/api/v3/connection/{connectionGuid}/pricelist/{priceListGuid}/price

Description

Fetches prices with promotions applied for a specific price list and connection. Supports pagination via pageIndex and pageSize.

Parameters

Parameter	Type	Description
`pageIndex`	int	Zero-based index (e.g., 0, 1, 2)
`pageSize`	int	Items per page (1 to 1000)

Example Request

GET https://sbx-api.vaultn.com/api/v3/connection/a1b2c3d4-e5f6-7890-abcd-1234567890ef/pricelist/987f6bcd-1234-5678-abcd-12345678abcd/price?pageIndex=0&pageSize=50

Example Response Snippet

{
  "count": 200,
  "payload": [
    {
      "productGuid": "prod-1234-abcd-5678-efgh",
      "productTitle": "Epic Game Key",
      "skus": [
        {
          "sku": "EGK-NA-PC",
          "provider": "PC",
          "regionCode": "NA",
          "prices": [
            {
              "priceListGuid": "987f6bcd-1234-5678-abcd-12345678abcd",
              "srp": 49.99,
              "purchasePrice": 35.00,
              "currencyCode": "USD",
              "isActivePromotion": true
            }
          ]
        }
      ]
    }
  ]
}

Common Mistakes to Avoid

Issue	Error Code	Fix
Invalid GUID format	400	Ensure GUID is correctly formatted and exists
Missing or wrong parameters	400	Validate `pageIndex` >= 0 and `1 <= pageSize <= 1000`
Unauthorized access	401	Check your authentication headers/token
Resource not found	404	Verify GUIDs point to accessible resources

Tips for Working with GUIDs

Always fetch fresh GUIDs using the /connection endpoint.
URL encode GUIDs if they contain special characters.
Validate GUIDs before use to avoid 400/404 errors.
Use pagination wisely for large datasets (pageSize up to 1000).

Conclusion

By correctly inserting GUIDs into your endpoint paths and including the right parameters, you can interact with VaultN's API seamlessly and get accurate data every time.