> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billbora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

# Quickstart

Get up and running with the Billbora API in under 5 minutes. This guide will walk you through making your first API call and creating your first invoice.

## Prerequisites

Before you begin, you'll need:

* A Billbora account ([sign up here](https://app.billbora.com/signup))
* Basic knowledge of REST APIs
* A tool to make HTTP requests (curl, Postman, or your preferred programming language)

## Step 1: Get Your API Credentials

<Steps>
  <Step title="Log into Billbora">
    Navigate to [app.billbora.com](https://app.billbora.com) and log in to your account.
  </Step>

  <Step title="Go to API Settings">
    In your dashboard, go to **Settings** → **API** → **Credentials**.
  </Step>

  <Step title="Generate API Key">
    Click **Generate New API Key** and copy the generated key.

    <Warning>
      Store this key securely - it won't be shown again!
    </Warning>
  </Step>
</Steps>

## Step 2: Make Your First API Call

Let's start by fetching your organization information:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    https://api.billbora.com/api/v1/organizations/me/ \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.billbora.com/api/v1/organizations/me/', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  })

  const organization = await response.json()
  console.log(organization)
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.billbora.com/api/v1/organizations/me/',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      }
  )

  organization = response.json()
  print(organization)
  ```

  ```typescript TypeScript theme={null}
  import { BillboraAPI } from '@billbora/sdk'

  const client = new BillboraAPI({
    apiKey: 'YOUR_API_KEY'
  })

  const organization = await client.organizations.getCurrent()
  console.log(organization)
  ```
</CodeGroup>

You should receive a response like this:

```json Response theme={null}
{
  "id": "org_1234567890",
  "name": "Your Organization",
  "subscription_tier": "growth",
  "subscription_status": "active",
  "created_at": "2025-01-01T00:00:00Z"
}
```

<Check>
  Great! Your API credentials are working correctly.
</Check>

## Step 3: Create Your First Client

Before creating an invoice, you need a client. Let's create one:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://api.billbora.com/api/v1/clients/ \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Acme Corporation",
      "email": "billing@acme.com",
      "phone": "+1-555-0123",
      "address": "123 Business Ave",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94102",
      "country": "US"
    }'
  ```

  ```javascript JavaScript theme={null}
  const client = await fetch('https://api.billbora.com/api/v1/clients/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Acme Corporation',
      email: 'billing@acme.com',
      phone: '+1-555-0123',
      address: '123 Business Ave',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    })
  })

  const newClient = await client.json()
  console.log(newClient)
  ```

  ```python Python theme={null}
  client_data = {
      'name': 'Acme Corporation',
      'email': 'billing@acme.com',
      'phone': '+1-555-0123',
      'address': '123 Business Ave',
      'city': 'San Francisco',
      'state': 'CA',
      'postal_code': '94102',
      'country': 'US'
  }

  response = requests.post(
      'https://api.billbora.com/api/v1/clients/',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json=client_data
  )

  client = response.json()
  print(client)
  ```

  ```typescript TypeScript   theme={null}
  const newClient = await client.clients.create({
    name: 'Acme Corporation',
    email: 'billing@acme.com',
    phone: '+1-555-0123',
    address: '123 Business Ave',
    city: 'San Francisco',
    state: 'CA',
    postal_code: '94102',
    country: 'US'
  })

  console.log(newClient)
  ```
</CodeGroup>

Save the client ID from the response - you'll need it for the invoice:

```json Response theme={null}
{
  "id": "client_1234567890",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z"
}
```

## Step 4: Create Your First Invoice

Now let's create an invoice for your new client:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://api.billbora.com/api/v1/invoices/ \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "client": "client_1234567890",
      "issue_date": "2025-01-15",
      "due_date": "2025-02-15",
      "line_items": [
        {
          "description": "Consulting Services",
          "quantity": 10,
          "unit_price": "150.00",
          "tax_rate": "10.00"
        },
        {
          "description": "Project Management",
          "quantity": 20,
          "unit_price": "100.00",
          "tax_rate": "10.00"
        }
      ],
      "notes": "Thank you for your business!",
      "terms": "Payment due within 30 days"
    }'
  ```

  ```javascript JavaScript theme={null}
  const invoice = await fetch('https://api.billbora.com/api/v1/invoices/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client: 'client_1234567890',
      issue_date: '2025-01-15',
      due_date: '2025-02-15',
      line_items: [
        {
          description: 'Consulting Services',
          quantity: 10,
          unit_price: '150.00',
          tax_rate: '10.00'
        },
        {
          description: 'Project Management', 
          quantity: 20,
          unit_price: '100.00',
          tax_rate: '10.00'
        }
      ],
      notes: 'Thank you for your business!',
      terms: 'Payment due within 30 days'
    })
  })

  const newInvoice = await invoice.json()
  console.log(newInvoice)
  ```

  ```python Python theme={null}
  invoice_data = {
      'client': 'client_1234567890',
      'issue_date': '2025-01-15',
      'due_date': '2025-02-15',
      'line_items': [
          {
              'description': 'Consulting Services',
              'quantity': 10,
              'unit_price': '150.00',
              'tax_rate': '10.00'
          },
          {
              'description': 'Project Management',
              'quantity': 20,
              'unit_price': '100.00',
              'tax_rate': '10.00'
          }
      ],
      'notes': 'Thank you for your business!',
      'terms': 'Payment due within 30 days'
  }

  response = requests.post(
      'https://api.billbora.com/api/v1/invoices/',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json=invoice_data
  )

  invoice = response.json()
  print(invoice)
  ```

  ```typescript TypeScript theme={null}
  const newInvoice = await client.invoices.create({
    client: 'client_1234567890',
    issue_date: '2025-01-15',
    due_date: '2025-02-15',
    line_items: [
      {
        description: 'Consulting Services',
        quantity: 10,
        unit_price: '150.00',
        tax_rate: '10.00'
      },
      {
        description: 'Project Management',
        quantity: 20,
        unit_price: '100.00', 
        tax_rate: '10.00'
      }
    ],
    notes: 'Thank you for your business!',
    terms: 'Payment due within 30 days'
  })

  console.log(newInvoice)
  ```
</CodeGroup>

You should receive a response with your new invoice:

```json Response theme={null}
{
  "id": "inv_1234567890",
  "invoice_number": "INV-001",
  "status": "draft",
  "client": {
    "id": "client_1234567890",
    "name": "Acme Corporation"
  },
  "issue_date": "2025-01-15",
  "due_date": "2025-02-15",
  "subtotal": "3500.00",
  "tax_amount": "350.00",
  "total_amount": "3850.00",
  "currency": "USD",
  "line_items": [
    {
      "description": "Consulting Services",
      "quantity": 10,
      "unit_price": "150.00",
      "tax_rate": "10.00",
      "total": "1650.00"
    },
    {
      "description": "Project Management",
      "quantity": 20,
      "unit_price": "100.00",
      "tax_rate": "10.00", 
      "total": "2200.00"
    }
  ],
  "public_url": "https://invoice.billbora.com/inv_1234567890",
  "pdf_url": "https://invoice.billbora.com/inv_1234567890/pdf",
  "created_at": "2025-01-15T10:30:00Z"
}
```

<Check>
  Congratulations! You've successfully created your first invoice.
</Check>

## Step 5: Send the Invoice

Now let's send the invoice to your client:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    https://api.billbora.com/api/v1/invoices/inv_1234567890/send/ \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "billing@acme.com"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.billbora.com/api/v1/invoices/inv_1234567890/send/', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'billing@acme.com'
    })
  })

  const result = await response.json()
  console.log(result)
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://api.billbora.com/api/v1/invoices/inv_1234567890/send/',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={'email': 'billing@acme.com'}
  )

  result = response.json()
  print(result)
  ```

  ```typescript TypeScript theme={null}
  const result = await client.invoices.send('inv_1234567890', {
    email: 'billing@acme.com'
  })

  console.log(result)
  ```
</CodeGroup>

The invoice will be sent via email, and you'll receive a confirmation:

```json Response theme={null}
{
  "message": "Invoice sent successfully",
  "sent_to": "billing@acme.com",
  "sent_at": "2025-01-15T10:35:00Z"
}
```

## What's Next?

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/authentication">
    Learn about our hybrid authentication system for frontend applications
  </Card>

  <Card title="Frontend Integration" icon="browser" href="/guides/frontend-integration">
    Integrate Billbora with React, Vue, or your preferred frontend framework
  </Card>

  <Card title="Webhooks Setup" icon="webhook" href="/webhooks/setup">
    Set up real-time event notifications for invoice and payment updates
  </Card>

  <Card title="Payment Processing" icon="credit-card" href="/resources/payments">
    Accept payments directly through your application using Stripe integration
  </Card>
</CardGroup>

## Common Next Steps

<AccordionGroup>
  <Accordion title="Set up webhook notifications">
    Configure webhooks to receive real-time updates about invoice status changes, payments, and other events:

    ```bash theme={null}
    curl -X POST \
      https://api.billbora.com/api/v1/webhooks/ \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://your-app.com/webhooks/billbora",
        "events": ["invoice.paid", "invoice.overdue", "payment.received"]
      }'
    ```
  </Accordion>

  <Accordion title="Accept payments">
    Enable your clients to pay invoices online by setting up Stripe integration:

    ```bash theme={null}
    curl -X POST \
      https://api.billbora.com/api/v1/invoices/inv_1234567890/payment-link/ \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Accordion>

  <Accordion title="Create recurring invoices">
    Set up subscription billing for recurring services:

    ```bash theme={null}
    curl -X POST \
      https://api.billbora.com/api/v1/recurring-invoices/ \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "client": "client_1234567890",
        "frequency": "monthly",
        "line_items": [...]
      }'
    ```
  </Accordion>

  <Accordion title="Generate reports">
    Access revenue reports and analytics:

    ```bash theme={null}
    curl -X GET \
      "https://api.billbora.com/api/v1/reports/revenue/?period=monthly&start_date=2025-01-01" \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup cols={3}>
  <Card title="API Reference" icon="book" href="/api-reference">
    Complete API documentation with all endpoints
  </Card>

  <Card title="Community" icon="users" href="https://community.billbora.com">
    Get help from other developers
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:api-support@billbora.com">
    Contact our support team
  </Card>
</CardGroup>

<Info>
  **Tip**: All examples in this guide use placeholder IDs. Replace them with the actual IDs returned by your API calls.
</Info>