# HYROS Installation: Direct API Integration

## OVERVIEW

This guide is for custom/developer integrations using the HYROS API directly.

**Ask user:** "What are you building? (Custom app, internal tool, webhook receiver, etc.)"

Understanding the use case will determine the best approach.

---

## REQUIREMENTS - Collect Before Starting

| Item | Ask User |
|------|----------|
| HYROS API Key | "Please paste your HYROS API key. Get it from: https://app.hyros.com/settings/api" |
| Developer Access | "Do you have developer/technical resources available?" |
| Use Case | "What data are you sending to HYROS? (leads, sales, custom events)" |

**IMPORTANT:** Store the API key securely - never expose it in client-side code.

---

## STEPS

### Step 1: Get Your API Key

**Direct URL:** https://app.hyros.com/settings/api

**If automating:** Navigate to API settings, copy the API key.

**If guiding user:** "Go to https://app.hyros.com/settings/api and copy your API key"

→ Confirm: "Do you have your API key?"

---

### Step 2: Review API Documentation

**If automating:** Fetch and review HYROS API documentation for available endpoints.

**If guiding user:**
"Review the HYROS API documentation for:
- Available endpoints
- Required fields
- Authentication method
- Rate limits"

→ Confirm: "Have you reviewed the API docs?"

---

### Step 3: Set Up Authentication

**If automating:** Configure API requests with proper headers.

**If guiding user:**
"Your API requests need:
- Header: `Authorization: Bearer YOUR_API_KEY`
- Content-Type: `application/json`"

Example:
```
curl -X POST https://api.hyros.com/v1/... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
```

→ Confirm: "Is authentication set up?"

---

### Step 4: Implement Your Integration

**If automating:** Write code to send data to HYROS based on user's use case.

**If guiding user:**
"Implement your integration:
1. Choose your endpoint based on data type (leads, sales, events)
2. Format your data as JSON
3. Send POST requests to HYROS
4. Handle responses and errors"

→ Confirm: "Is your code written?"

---

### Step 5: Test with Sample Data

**If automating:** Send test requests to verify integration works.

**If guiding user:**
"Test your integration:
1. Send a test request with sample data
2. Check the API response for success/errors
3. Verify data appears in HYROS"

→ Confirm: "Did the test work?"

---

### Step 6: Verify in HYROS

**Direct URL:** https://app.hyros.com/

**If automating:** Check HYROS dashboard for test data.

**If guiding user:** "Check HYROS to confirm your test data came through"

→ Confirm: "Can you see the data in HYROS?"

---

### Step 7: Deploy to Production

**If automating:** Deploy integration code to production environment.

**If guiding user:**
"Deploy your integration:
1. Move code to production
2. Use production API key
3. Monitor for errors
4. Set up logging"

→ Confirm: "Is the integration live?"

---

## TROUBLESHOOTING

- **401 Unauthorized:** API key is invalid or expired
- **400 Bad Request:** Check JSON format and required fields
- **429 Too Many Requests:** You're hitting rate limits - add delays
- **500 Server Error:** Try again; if persistent, contact HYROS support

---

## COMMON USE CASES

### Sending Leads
```json
POST /v1/leads
{
  "email": "customer@example.com",
  "source": "your_source",
  "tags": ["tag1", "tag2"]
}
```

### Sending Sales
```json
POST /v1/sales
{
  "email": "customer@example.com",
  "amount": 99.99,
  "product": "Product Name"
}
```

### Sending Events
```json
POST /v1/events
{
  "email": "customer@example.com",
  "event": "custom_event_name"
}
```

---

## Source
Synced from: docsContent.ts (apiGuide)
Last synced: 2026-01-03