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

# Expanding Objects

> Include related objects in API responses

## Overview

Many objects in the Contazen API contain references to other objects via their IDs. By default, these references are returned as simple ID strings. However, you can request the full objects by using the `expand` parameter.

## Usage

Include the `expand` parameter in your request to retrieve related objects:

<CodeGroup>
  ```bash cURL Array Format theme={null}
  curl https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -G \
    -d expand[]=lines \
    -d expand[]=client
  ```

  ```bash cURL Comma-separated Format theme={null}
  curl https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
    -G \
    -d expand=lines,client
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e?' + 
    new URLSearchParams({
      'expand[]': ['lines', 'client']
    }), {
    headers: {
      'Authorization': 'Bearer sk_live_YOUR_API_KEY'
    }
  });
  ```

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

  response = requests.get(
      'https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e',
      params={'expand': ['lines', 'client']},
      headers={'Authorization': 'Bearer sk_live_YOUR_API_KEY'}
  )
  ```
</CodeGroup>

## Supported Expansions

### Invoices

When retrieving invoices, you can expand the following objects:

| Field      | Description                                   |
| ---------- | --------------------------------------------- |
| `lines`    | Invoice line items with full details          |
| `payments` | Payment records associated with the invoice   |
| `client`   | Full client object instead of just client\_id |
| `efactura` | E-Factura submission details (if applicable)  |

### Example Without Expansion

```json theme={null}
{
  "id": "inv_1a2b3c4d5e",
  "object": "invoice",
  "client_id": "cli_9z8y7x6w5v",
  "lines": ["line_1", "line_2"],
  "total": 119.00
}
```

### Example With Expansion

```json theme={null}
{
  "id": "inv_1a2b3c4d5e",
  "object": "invoice",
  "client": {
    "id": "9z8y7x6w5v",
    "object": "client",
    "name": "Tech Solutions SRL",
    "email": "contact@techsolutions.ro",
    "cui": "RO98765432",
    "address": "Bd. Tehnologie nr. 100",
    "city": "București, Sectorul 2"
  },
  "lines": [
    {
      "id": "line_1",
      "description": "Web Development Services",
      "quantity": 1,
      "price": 100.00,
      "vat_rate": 19,
      "subtotal": 100.00,
      "vat_amount": 19.00,
      "total": 119.00
    }
  ],
  "total": 119.00
}
```

## Multiple Expansions

You can expand multiple objects in a single request:

```bash theme={null}
# Expand both client and lines
curl https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e?expand[]=client&expand[]=lines \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

## Performance Considerations

<Warning>
  Expanding objects increases response size and processing time. Only expand objects when you need the additional data.
</Warning>

### Best Practices

1. **Expand selectively** - Only expand objects you actually need
2. **Cache expanded responses** - Expanded objects change less frequently
3. **Use in detail views** - Expand when showing single items, not lists
4. **Consider pagination** - Be mindful of response size when expanding in list endpoints

## List Endpoints

The expand parameter works with both individual object endpoints and list endpoints:

```bash theme={null}
# Get all invoices with expanded client data
curl https://api.contazen.ro/v1/invoices?expand[]=client \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

<Note>
  When using expand with list endpoints, be aware that it will expand the objects for every item in the list, which can significantly increase response size.
</Note>

## Invalid Expansions

If you request an invalid expansion, it will be ignored. The API only expands valid fields:

```bash theme={null}
# 'invalid_field' will be ignored
curl https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e?expand[]=client&expand[]=invalid_field \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

The response will include the expanded `client` but ignore `invalid_field`.