​
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: 
curl https://api.contazen.ro/v1/invoices/inv_1a2b3c4d5e \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -G \
  -d expand[]=lines \
  -d expand[]=client

​
Supported Expansions

​
Invoices

When retrieving invoices, you can expand the following objects:
FieldDescription
linesInvoice line items with full details
paymentsPayment records associated with the invoice
clientFull client object instead of just client_id
efacturaE-Factura submission details (if applicable)

​
Example Without Expansion

{
  "id": "inv_1a2b3c4d5e",
  "object": "invoice",
  "client_id": "cli_9z8y7x6w5v",
  "lines": ["line_1", "line_2"],
  "total": 119.00
}

​
Example With Expansion

{
  "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: 
# 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

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

​
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: 
# Get all invoices with expanded client data
curl https://api.contazen.ro/v1/invoices?expand[]=client \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
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.

​
Invalid Expansions

If you request an invalid expansion, it will be ignored. The API only expands valid fields: 
# '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.