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

# Quickstart

> Make your first API call in 5 minutes

# Quickstart Guide

Follow this guide to make your first API call to the Okasie Partner API.

## Prerequisites

Before you begin, you need:

<Check>A partner API secret (contact [info@okasie.be](mailto:info@okasie.be) to request access)</Check>
<Check>A tool to make HTTP requests (cURL, Postman, or your programming language)</Check>

## Step 1: Test Authentication

Let's verify your API credentials work correctly.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://www.okasie.be/api/external/v1/listings?pageSize=1" \
    -H "Authorization: Bearer YOUR_API_SECRET"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://www.okasie.be/api/external/v1/listings?pageSize=1",
    {
      headers: {
        Authorization: `Bearer ${process.env.PARTNER_SECRET}`,
      },
    }
  );

  const data = await response.json();
  console.log(data);
  ```

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

  url = "https://www.okasie.be/api/external/v1/listings"
  params = {"pageSize": 1}
  headers = {"Authorization": f"Bearer {os.getenv('PARTNER_SECRET')}"}

  response = requests.get(url, params=params, headers=headers)
  print(response.json())
  ```
</CodeGroup>

<Note>
  Replace `YOUR_API_SECRET` with your actual API secret. Never commit secrets to version control.
</Note>

### Expected Response

A successful response (HTTP 200) looks like:

```json theme={null}
{
  "data": [
    {
      "id": "46c7f6c9-70f7-4f98-8c32-12f1a67c6f2e",
      "title": "Opel Corsa 1.2 Turbo",
      "status": "active",
      "price": 19995,
      ...
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 1,
    "totalItems": 123,
    "totalPages": 123
  },
  "meta": {
    "partner": {
      "id": "your-partner-id",
      "name": "Your Partner Name"
    }
  }
}
```

## Step 2: Create Your First Listing

Now let's create a vehicle listing.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://www.okasie.be/api/external/v1/listings/MY-REF-001" \
    -H "Authorization: Bearer YOUR_API_SECRET" \
    -H "Content-Type: application/json" \
    -d '{
      "dealerProfileId": "YOUR_DEALER_PROFILE_ID",
      "status": "active",
      "title": "Opel Corsa 1.2 Turbo",
      "price": 19995,
      "brand": "Opel",
      "model": "Corsa",
      "year": 2021,
      "mileage": 25000,
      "fuelType": "petrol",
      "carPassUrl": "https://public.car-pass.be/vhr/example",
      "postalCode": "9000",
      "city": "Gent",
      "province": "Oost-Vlaanderen",
      "images": ["https://your-cdn.com/car-image.jpg"]
    }'
  ```

  ```javascript Node.js theme={null}
  const listing = {
    dealerProfileId: "YOUR_DEALER_PROFILE_ID",
    status: "active",
    title: "Opel Corsa 1.2 Turbo",
    price: 19995,
    brand: "Opel",
    model: "Corsa",
    year: 2021,
    mileage: 25000,
    fuelType: "petrol",
    carPassUrl: "https://public.car-pass.be/vhr/example",
    postalCode: "9000",
    city: "Gent",
    province: "Oost-Vlaanderen",
    images: ["https://your-cdn.com/car-image.jpg"],
  };

  const response = await fetch(
    "https://www.okasie.be/api/external/v1/listings/MY-REF-001",
    {
      method: "PUT",
      headers: {
        Authorization: `Bearer ${process.env.PARTNER_SECRET}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(listing),
    }
  );

  const data = await response.json();
  console.log(data);
  ```

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

  url = "https://www.okasie.be/api/external/v1/listings/MY-REF-001"
  headers = {
      "Authorization": f"Bearer {os.getenv('PARTNER_SECRET')}",
      "Content-Type": "application/json"
  }
  payload = {
      "dealerProfileId": "YOUR_DEALER_PROFILE_ID",
      "status": "active",
      "title": "Opel Corsa 1.2 Turbo",
      "price": 19995,
      "brand": "Opel",
      "model": "Corsa",
      "year": 2021,
      "mileage": 25000,
      "fuelType": "petrol",
      "carPassUrl": "https://public.car-pass.be/vhr/example",
      "postalCode": "9000",
      "city": "Gent",
      "province": "Oost-Vlaanderen",
      "images": ["https://your-cdn.com/car-image.jpg"]
  }

  response = requests.put(url, json=payload, headers=headers)
  print(response.json())
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "data": {
    "listingId": "0c52cae7-bcaa-4b37-be0d-1b78c92c5225",
    "externalReference": "MY-REF-001",
    "status": "active",
    "created": true
  }
}
```

## Step 3: Update or Mark as Sold

### Update a Listing

Simply call PUT again with the same external reference:

```bash theme={null}
curl -X PUT "https://www.okasie.be/api/external/v1/listings/MY-REF-001" \
  -H "Authorization: Bearer YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"dealerProfileId": "...", "title": "Updated Title", "price": 18995, ...}'
```

### Mark as Sold

```bash theme={null}
curl -X DELETE "https://www.okasie.be/api/external/v1/listings/MY-REF-001" \
  -H "Authorization: Bearer YOUR_API_SECRET"
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about scopes and security best practices
  </Card>

  <Card title="Incremental Sync" icon="arrows-rotate" href="/guides/incremental-sync">
    Set up efficient incremental synchronization
  </Card>

  <Card title="Bulk Operations" icon="layer-group" href="/api-reference/listings/bulk-upsert">
    Upload up to 100 listings at once
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/errors">
    Handle errors gracefully
  </Card>
</CardGroup>