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

# Quickstart

> Start using the North API in 5 minutes

# Quickstart Guide

Get up and running with the North API in just a few minutes.

## Prerequisites

* A North account ([sign up here](https://northreports.com/signup))
* Your API key ([get one here](https://northreports.com/dashboard/settings))

## Step 1: Test your connection

Let's verify your API key works by fetching your account info:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.northreports.com/v1/users/me" \
    -H "Authorization: Bearer north_sk_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const API_KEY = 'north_sk_live_YOUR_KEY';

  const response = await fetch('https://api.northreports.com/v1/users/me', {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  const { data } = await response.json();
  console.log('Team:', data.team.name);
  console.log('Reports:', data.team.reports_count);
  ```

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

  API_KEY = 'north_sk_live_YOUR_KEY'

  response = requests.get(
      'https://api.northreports.com/v1/users/me',
      headers={'Authorization': f'Bearer {API_KEY}'}
  )

  data = response.json()['data']
  print(f"Team: {data['team']['name']}")
  print(f"Reports: {data['team']['reports_count']}")
  ```
</CodeGroup>

You should see your team information and API key details.

## Step 2: List your reports

Fetch all your existing North reports:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.northreports.com/v1/reports" \
    -H "Authorization: Bearer north_sk_live_YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.northreports.com/v1/reports?limit=10', {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  const { data, total } = await response.json();
  console.log(`Found ${total} reports`);
  data.forEach(report => {
    console.log(`- ${report.address}, ${report.city} ($${report.price})`);
  });
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.northreports.com/v1/reports',
      params={'limit': 10},
      headers={'Authorization': f'Bearer {API_KEY}'}
  )

  result = response.json()
  print(f"Found {result['total']} reports")
  for report in result['data']:
      print(f"- {report['address']}, {report['city']} (${report['price']})")
  ```
</CodeGroup>

## Step 3: Create a new report

Let's create a North report programmatically:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST \
    "https://api.northreports.com/v1/reports" \
    -H "Authorization: Bearer north_sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "address": "123 Main Street",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "price": 450000,
      "bedrooms": 3,
      "bathrooms": 2,
      "square_feet": 1850,
      "year_built": 2010,
      "property_type": "Single Family"
    }'
  ```

  ```javascript JavaScript theme={null}
  const newReport = {
    address: '123 Main Street',
    city: 'Austin',
    state: 'TX',
    zip: '78701',
    price: 450000,
    bedrooms: 3,
    bathrooms: 2,
    square_feet: 1850,
    year_built: 2010,
    property_type: 'Single Family'
  };

  const response = await fetch('https://api.northreports.com/v1/reports', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(newReport)
  });

  const { data, message } = await response.json();
  console.log(message);
  console.log('Report ID:', data.id);
  ```

  ```python Python theme={null}
  new_report = {
      'address': '123 Main Street',
      'city': 'Austin',
      'state': 'TX',
      'zip': '78701',
      'price': 450000,
      'bedrooms': 3,
      'bathrooms': 2,
      'square_feet': 1850,
      'year_built': 2010,
      'property_type': 'Single Family'
  }

  response = requests.post(
      'https://api.northreports.com/v1/reports',
      json=new_report,
      headers={'Authorization': f'Bearer {API_KEY}'}
  )

  result = response.json()
  print(result['message'])
  print(f"Report ID: {result['data']['id']}")
  ```
</CodeGroup>

<Tip>
  The report is created as a draft by default. You can update it or publish it later.
</Tip>

## Step 4: Update the report

Add more details to your report:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH \
    "https://api.northreports.com/v1/reports/REPORT_ID" \
    -H "Authorization: Bearer north_sk_live_YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "description": "Beautiful corner lot with mature trees",
      "executive_summary": "This charming 3-bed home offers excellent value in a prime Austin location."
    }'
  ```

  ```javascript JavaScript theme={null}
  const reportId = 'YOUR_REPORT_ID';

  const updates = {
    description: 'Beautiful corner lot with mature trees',
    executive_summary: 'This charming 3-bed home offers excellent value in a prime Austin location.'
  };

  const response = await fetch(`https://api.northreports.com/v1/reports/${reportId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updates)
  });

  const { message } = await response.json();
  console.log(message);
  ```

  ```python Python theme={null}
  report_id = 'YOUR_REPORT_ID'

  updates = {
      'description': 'Beautiful corner lot with mature trees',
      'executive_summary': 'This charming 3-bed home offers excellent value in a prime Austin location.'
  }

  response = requests.patch(
      f'https://api.northreports.com/v1/reports/{report_id}',
      json=updates,
      headers={'Authorization': f'Bearer {API_KEY}'}
  )

  print(response.json()['message'])
  ```
</CodeGroup>

## Understanding rate limits

Every response includes rate limit headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 985
X-RateLimit-Reset: 1705774800
```

* **Limit**: Maximum requests per hour
* **Remaining**: How many you have left
* **Reset**: Unix timestamp when your quota resets

## Error handling

Always check for errors in your code:

```javascript theme={null}
const response = await fetch('https://api.northreports.com/v1/reports', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${error.error.status}: ${error.error.message}`);
  return;
}

const data = await response.json();
// Process successful response
```

## Next steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all available endpoints
  </Card>

  <Card title="Zapier Integration" icon="bolt" href="/guides/zapier-integration">
    Connect North to Zapier
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Get real-time notifications
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/rate-limits">
    Understand usage limits
  </Card>
</CardGroup>