API

​

Accessing API Management

​

Page Layout

​

API Keys Tab

• View: All API keys with details (name, scopes, operations, status)
• Create: Generate new API keys with custom permissions
• Revoke: Delete API keys to remove access

​

Usage Tab

• Charts: Visual analytics of API usage over time (30 days)
• Metrics: Total requests, success rate, response time
• Endpoints: Breakdown of requests per endpoint

​

Documentation Tab

• Integration Guides: Power BI, Excel integration steps
• Authentication: How to use API keys in requests
• Operations: HTTP methods (GET, POST, PUT, DELETE)
• Endpoints: Complete API reference with examples

​

API Keys Tab

​

API Keys Table

• Name: API key name (descriptive identifier)
• Scopes: Resources the key can access (valuations, player-sales, clubs)
• Operations: HTTP methods allowed (GET, POST, PUT, DELETE) with color chips
  • Blue (GET) - Read
  • Green (POST) - Create
  • Yellow (PUT) - Update
  • Red (DELETE) - Delete
• Created: Date key was created
• Created By: User who created the key (name or email)
• Last Used: Last time key was used (or “Never”)
• Status: Active (green) or Inactive (gray) badge
• Actions: Revoke button (red trash icon)

​

Empty State

• Icon: Key icon
• Title: “No API keys yet”
• Message: “Create your first API key to get started”
• Action: Click “Create API Key” button in header

​

Create API Key

​

Opening Create Modal

• Click “Create API Key” button (page header, top right)
• Available on all tabs (button always visible)

• If in demo mode, shows “Upgrade Required” modal instead
• Must upgrade to paid plan to create API keys

​

Create API Key Modal

• Title: “Create API Key”
• Close button: X (top right)
• Form fields: Name, Description, Scopes, Operations
• Action buttons: Cancel, Create API Key

​

Form Fields

• Label: “Key Name”
• Placeholder: “My Integration Key”
• Validation:
  • Required field
  • Must be unique (checks against existing keys)
  • Max 50 characters

• Label: “Description”
• Placeholder: “What this key will be used for…”
• Helper: “Describe the purpose of this API key”
• Max: 200 characters

• Label: “Scopes”
• Helper: “Select which resources this key can access”
• Options: Checkboxes for each scope
  • ☑ Valuations - Access valuation data
  • ☑ Player Sales - Access player transfer data
  • ☑ Clubs - Access club information
• Validation: At least one scope required

• Label: “Operations”
• Helper: “Select which HTTP operations this key can perform”
• Options: Checkboxes for each operation
  • ☑ GET (Read) - Retrieve data
  • ☑ POST (Create) - Create new records
  • ☑ PUT (Update) - Modify existing records
  • ☑ DELETE (Delete) - Remove records
• Validation: At least one operation required

​

API Key Creation Process

1. Enter unique key name
2. Add optional description
3. Select scopes (resources)
4. Select operations (HTTP methods)
5. Click “Create API Key”

• API key is generated and displayed in a modal
• Format: vly_<random_string> (e.g., vly_abc123def456...)
• Copy Button: Click to copy key to clipboard
• Important Warning: “This is the only time you’ll see this key. Copy it now and store it securely.”

• Store key in password manager or secure storage
• Never commit to version control
• Never share publicly
• Cannot view key again after closing modal

• New key appears in API Keys table
• Status: Active (green badge)
• Last Used: Never (not yet used)
• All selected scopes and operations visible

​

Revoking API Keys

​

Revoke Process

1. Find API key in table
2. Click red trash icon (Actions column)
3. Confirmation modal appears

• Title: “Revoke API Key”
• Message: “Are you sure you want to revoke the API key ‘[Name]’? This action cannot be undone and any applications using this key will immediately lose access.”
• Buttons:
  • Revoke (red, destructive)
  • Cancel (gray)

• API key deleted from database
• Key removed from table
• All requests using this key will fail with 401 Unauthorized

​

Usage Tab

​

Requests Over Time Chart

• X-axis: Date (last 30 days)
• Y-axis: Number of requests
• Line: Blue line with dots for each day
• Hover: Tooltip shows exact request count
• Grid: Cartesian grid for easy reading

• Icon: Chart icon
• Title: “No API usage data yet”
• Message: “Start making API requests to see usage statistics”

​

Summary Metrics Cards

• Value: Total API requests (last 30 days)
• Change: Percentage increase/decrease from previous period
• Trend: Up (green) or Down (red) indicator

• Value: Percentage of successful requests (200-299 status)
• Format: “98.5%”
• No trend indicator

• Value: Average API response time in milliseconds
• Format: “125ms”
• No trend indicator

​

Requests by Endpoint

• Endpoint: Full endpoint path (e.g., /api/v1/valuations)
• Request Count: Number of requests
• Success Rate: Percentage successful (green text)
• Progress Bar: Visual representation of usage (width = % of total)

​

Documentation Tab

​

Integration Guides

​

Power BI Integration

1. Open Power BI Desktop
2. Get Data → Web
3. Enter API URL with your API key
4. Transform data as needed
5. Create visualizations

​

Excel Integration

1. Data → Get Data → From Web
2. Enter API URL
3. Power Query Editor opens
4. Load to worksheet

​

Authentication

?api_key=YOUR_API_KEY&club_id=YOUR_CLUB_ID

https://valiyou.com/api/v1/valuations?api_key=vly_abc123&club_id=org_xyz789

• api_key - Your API key (required)
• club_id - Your organization ID (required)

​

HTTP Operations

​

GET (Read)

• Method: GET
• Chip Color: Blue
• Purpose: Retrieve and read data from your organization
• Use Case: Read-only integrations (Power BI, Excel, analytics)

​

POST (Create)

• Method: POST
• Chip Color: Green
• Purpose: Create new records in your organization
• Use Case: Automated data entry, imports

​

PUT (Update)

• Method: PUT
• Chip Color: Yellow
• Purpose: Update existing records in your organization
• Use Case: Data synchronization, corrections

​

DELETE (Delete)

• Method: DELETE
• Chip Color: Red
• Purpose: Delete records from your organization
• Use Case: Cleanup, data management

​

API Endpoints

​

GET /api/v1/clubs

• api_key (string, required) - Your API key
• club_id (string, required) - Your club ID

• name (string) - Club name
• address (string) - Full club address (street, postal code, city, country)
• base_currency (string) - Base currency code (e.g., EUR, USD, DKK)

curl -X GET "https://valiyou.com/api/v1/clubs?api_key=YOUR_API_KEY&club_id=YOUR_CLUB_ID"

{
  "name": "FC Example",
  "address": "123 Stadium Road, 12345 City, Country",
  "base_currency": "EUR"
}

​

GET /api/v1/valuations

• api_key (string, required) - Your API key
• club_id (string, required) - Your club ID
• from_date (string, optional) - Filter from date (YYYY-MM-DD)
• to_date (string, optional) - Filter to date (YYYY-MM-DD)

• id (string) - Valuation unique ID
• club_id (string) - Club ID
• valuation_date (string) - Date of the valuation (YYYY-MM-DD)
• created_at (string) - Creation timestamp
• merch_revenue (number) - Merchandise revenue
• matchday_revenue (number) - Matchday revenue
• player_sales_value (number) - Total player sales value
• tv_duration_min (number) - TV exposure duration in minutes
• tv_size_category (string) - TV logo size (S, M, L, XL)
• tv_cpm (number) - TV cost per thousand impressions
• tv_viewers (number) - TV viewers count
• webtv_views (number) - Web TV views
• webtv_cpm (number) - Web TV CPM
• pr_reach (number) - PR reach
• pr_cpm (number) - PR CPM
• digital_impressions (number) - Digital impressions
• digital_cpm (number) - Digital CPM
• social_followers (number) - Social media followers
• social_followers_cpm (number) - Social followers CPM
• social_impressions (number) - Social media impressions
• social_impressions_cpm (number) - Social impressions CPM
• social_engagements (number) - Social media engagements
• social_cpm (number) - Social engagements CPM
• attendance (number) - Match attendance
• attendance_cpm (number) - Attendance CPM
• hospitality_guests (number) - Hospitality guests count
• hospitality_value_per_guest (number) - Value per hospitality guest
• brand_popularity (number) - Brand popularity score (1-10)
• brand_csr (number) - Brand CSR score (1-10)
• brand_culture (number) - Brand culture score (1-10)
• brand_loyalty (number) - Brand loyalty score (1-10)
• calculated_sales_value (number) - Calculated total sales value
• calculated_media_value (number) - Calculated total media value
• qualitative_multiplier (number) - Brand quality multiplier
• final_total_value (number) - Final total attention valuation

curl -X GET "https://valiyou.com/api/v1/valuations?api_key=YOUR_API_KEY&club_id=YOUR_CLUB_ID"

curl -X GET "https://valiyou.com/api/v1/valuations?api_key=YOUR_API_KEY&club_id=YOUR_CLUB_ID&from_date=2024-01-01&to_date=2024-12-31"

​

GET /api/v1/player-sales

• api_key (string, required) - Your API key
• club_id (string, required) - Your club ID
• from_date (string, optional) - Filter from date (YYYY-MM-DD)
• to_date (string, optional) - Filter to date (YYYY-MM-DD)

• id (string) - Player sale unique ID
• valuation_id (string) - Associated valuation ID
• valuation_date (string) - Date of the valuation (YYYY-MM-DD)
• player_name (string) - Name of the player
• sale_value (number) - Sale/transfer value
• created_at (string) - Creation timestamp
• updated_at (string) - Last update timestamp

curl -X GET "https://valiyou.com/api/v1/player-sales?api_key=YOUR_API_KEY&club_id=YOUR_CLUB_ID"

​

Rate Limits

• ✅ Unlimited Requests: No rate limits for Professional/Enterprise plans
• ⚠️ Fair Use: Excessive usage may be flagged for review
• 📊 Monitoring: All requests are logged for usage analytics

• Potential per-minute or per-hour limits
• Different tiers based on plan
• Will be communicated in advance if implemented

​

Error Handling

​

Success Responses

• 200 OK - Request successful, data returned
• 201 Created - Resource created successfully (POST)
• 204 No Content - Request successful, no data returned (DELETE)

​

Client Errors (4xx)

• 400 Bad Request - Invalid request format or parameters
• 401 Unauthorized - Invalid or missing API key
• 403 Forbidden - API key doesn’t have required scope/operation
• 404 Not Found - Endpoint or resource doesn’t exist
• 429 Too Many Requests - Rate limit exceeded (if implemented)

​

Server Errors (5xx)

• 500 Internal Server Error - Unexpected server error
• 503 Service Unavailable - Temporary service disruption

{
  "error": "Unauthorized",
  "message": "Invalid API key provided"
}

​

Permissions

​

Common Use Cases

​

Power BI Integration

1. Navigate to Platform → API
2. Click “Create API Key”
3. Enter name: “Power BI Dashboard”
4. Description: “Read-only access for Power BI reports”
5. Select scopes: ☑ Valuations, ☑ Player Sales, ☑ Clubs
6. Select operations: ☑ GET (Read only)
7. Click “Create API Key”
8. Copy generated key (e.g., vly_abc123...)
9. Store key securely
10. Open Power BI Desktop
11. Get Data → Web
12. Enter URL: https://valiyou.com/api/v1/valuations?api_key=vly_abc123&club_id=org_xyz
13. Transform data in Power Query
14. Create visualizations

​

Excel Integration

1. Create API key (same as Power BI steps 1-9)
2. Open Excel
3. Data → Get Data → From Web
4. Enter URL with API key and club ID
5. Power Query Editor opens
6. Transform data as needed
7. Click “Close & Load” to load to worksheet
8. Set up automatic refresh (optional)

​

Data Export for Analysis

1. Create API key with GET operation
2. Use curl or programming language to fetch data:
   Copy

   curl "https://valiyou.com/api/v1/valuations?api_key=YOUR_KEY&club_id=YOUR_ID" > valuations.json
   

3. Process JSON data in your analytics tool
4. Schedule regular exports with cron job or task scheduler

​

Automated Data Entry

1. Create API key with POST operation
2. Select specific scopes (e.g., Valuations)
3. Build integration to create valuations automatically:
   Copy

   curl -X POST "https://valiyou.com/api/v1/valuations?api_key=YOUR_KEY&club_id=YOUR_ID" \
     -H "Content-Type: application/json" \
     -d '{"valuation_date": "2024-01-15", "merch_revenue": 50000, ...}'
   

​

Troubleshooting

​

Can’t Access API Page

• No API permission
• Not an Admin

• Request API permission from Admin
• Ask owner to grant Admin role

​

Can’t Create API Key (Demo Mode)

• Organization is in demo mode
• Free trial expired

• Upgrade to paid plan: Platform → Billing
• Contact sales for Enterprise plan

​

401 Unauthorized Errors

• API key invalid or typo
• API key revoked
• API key not included in request
• Using wrong club_id

• Verify API key is correct (copy-paste carefully)
• Check if key is still active in API Keys table
• Ensure api_key parameter is in URL
• Verify club_id matches your organization

• Create new API key if current one is revoked
• Double-check URL format and parameters
• Test with curl to isolate integration issues

​

403 Forbidden Errors

• API key doesn’t have required scope
• API key doesn’t have required operation
• Trying to access another organization’s data

• Review key’s scopes in API Keys table
• Review key’s operations in API Keys table
• Verify club_id matches your organization

• Create new API key with required scopes/operations
• Or revoke old key and create replacement with broader permissions

​

No Data Returned (Empty Array)

• No data matches filter criteria
• Date range filter too restrictive
• Organization has no valuations yet

• Remove date filters and try again
• Verify organization has created valuations
• Check if data exists in Valiyou platform

• Adjust date range: from_date and to_date parameters
• Create valuations if none exist
• Test with /api/v1/clubs endpoint to verify connectivity

​

Usage Statistics Not Showing

• No API requests made yet
• Statistics cache not updated (updates every 5 minutes)
• Network error fetching usage data

• Make some API requests first
• Wait 5 minutes for cache to refresh
• Refresh browser page
• Check browser console for errors

​

Security Best Practices

• ✅ Create separate keys for each integration
• ✅ Use descriptive names (e.g., “Power BI Production”, “Excel Finance”)
• ✅ Grant minimum required scopes and operations
• ✅ Store keys in password managers or environment variables
• ✅ Revoke unused or compromised keys immediately
• ❌ Never commit keys to version control
• ❌ Never share keys via email or chat
• ❌ Never log keys in application logs

• ✅ Always use HTTPS for API requests
• ✅ Implement error handling for failed requests
• ✅ Use retry logic with exponential backoff
• ✅ Monitor API usage regularly
• ❌ Don’t hardcode keys in application code
• ❌ Don’t expose keys in client-side JavaScript
• ❌ Don’t reuse keys across environments (dev/staging/prod)

• Review API keys quarterly
• Remove keys for terminated integrations
• Check “Last Used” column for inactive keys
• Monitor “Usage” tab for unusual activity

​

Next Steps