Creating a Community in One Call¶

The POST /core/api/communities endpoint accepts an optional preload object that lets you create members, meters, contracts, resources, and bilateral prices in a single API call, instead of the multi-step sequence described in the step-by-step guide.

How `*_ref` References Work¶

Within the preload object, entities are linked using *_ref fields rather than UUIDs — because UUIDs don't exist yet at request time. A ref is any arbitrary string you choose; it acts as a temporary client-side identifier resolved entirely within the single request.

Field	Where it appears	What it resolves
`members[].ref`	On each member	`contracts[].member_ref`, `ownerships[].member_ref`, `fixed_bilateral_prices[].provider_ref` / `receiver_ref`
`meters[].ref`	On each meter	`meters[].cpe_ref` (internal meters pointing to their CPE), `resources[].meter_ref`

*_ref values are not stored

Once the call completes, RECreation assigns UUIDs to all created entities and discards the *_ref strings. All subsequent API calls must use the returned UUIDs.

Structural Differences from Step-by-Step¶

Aspect	Step-by-step	Preload
Contracts	Created separately via `/meters/{meter_id}/contracts`	Embedded in each CPE meter as `contracts[]`
Meter link for internal meters	`cpe_id` (UUID)	`cpe_ref` (ref string)
Resource → meter link	`meter_id` (UUID)	`meter_ref` (ref string)
Resource ownership	`ownerships_payload[].user_id`	`ownerships[].member_ref`
Bilateral prices	Per-interval via `/bilateral-prices` (€/MWh)	Static per-pair in `fixed_bilateral_prices` (€/kWh), applied to every interval

Full Example¶

This example creates a Promoter-Anchor community with:

1 Anchor member — Prosumer CPE (IAC), with an internal house meter and an internal PV meter
1 Promoter member — owns the PV generation resource (SCPU) behind the Anchor CPE
1 OffTaker member (Consumer/NonHost) — Consumer CPE (IC)
Contracts for Anchor and OffTaker CPEs
Bilateral prices: Promoter → Anchor at 0.07 €/kWh, Promoter → OffTaker at 0.10 €/kWh

POST /core/api/communities

{
  "name": "My Community",
  "identifier": "CommunityACC",
  "type": "PROD",
  "method_alloc_coeff": "PROPORTIONAL",
  "market_rate": "FIXED_BILATERAL_PRICE",
  "preload": {
    "members": [
      {
        "ref": "AnchorRef",
        "name": "Anchor",
        "status": "ACTIVE",
        "is_host": true,
        "is_promoter": false
      },
      {
        "ref": "PromoterRef",
        "name": "Promoter",
        "status": "ACTIVE",
        "is_host": false,
        "is_promoter": true
      },
      {
        "ref": "OffTakerRef",
        "name": "OffTaker",
        "status": "ACTIVE",
        "is_host": true,
        "is_promoter": false
      }
    ],
    "meters": [
      {
        "ref": "CPEAnchorRef",
        "identifier": "PT000...1BB",
        "type": "CPE",
        "ord": "E-Redes",
        "installation_type": "IAC",
        "production_identifier": "PT000...1BB-PROD",
        "contracts": [
          {
            "member_ref": "AnchorRef",
            "buy_type": "NO_VALUES",
            "sell_type": "NO_VALUES",
            "voltage_level": "BTN simples",
            "tariff_cycle": "TETRA_SEMANAL",
            "with_holidays": false,
            "contracted_power": 6.9,
            "validity": "2025-01-01"
          }
        ]
      },
      {
        "ref": "CPEOffTakerRef",
        "identifier": "PT000...1AA",
        "type": "CPE",
        "ord": "E-Redes",
        "installation_type": "IC",
        "contracts": [
          {
            "member_ref": "OffTakerRef",
            "buy_type": "NO_VALUES",
            "sell_type": "NO_VALUES",
            "voltage_level": "BTN simples",
            "tariff_cycle": "TETRA_SEMANAL",
            "with_holidays": false,
            "contracted_power": 6.9,
            "validity": "2025-01-01"
          }
        ]
      },
      {
        "ref": "InternalAnchorRef",
        "identifier": "HouseMeter",
        "type": "INTERNAL",
        "installation_type": "IC",
        "cpe_ref": "CPEAnchorRef"
      },
      {
        "ref": "InternalPVRef",
        "identifier": "PVMeter",
        "type": "INTERNAL",
        "installation_type": "IPR",
        "cpe_ref": "CPEAnchorRef"
      }
    ],
    "resources": [
      {
        "ref": "AnchorResourceRef",
        "name": "Anchor House",
        "type": "IU",
        "status": "ACTIVE",
        "meter_ref": "InternalAnchorRef",
        "ownerships": [
          {
            "member_ref": "AnchorRef",
            "perc_ownership": 100
          }
        ],
        "iu_payload": {
          "sum_certified_power": 0,
          "ic_voltage_level": "BTN simples"
        }
      },
      {
        "ref": "PromoterPVRef",
        "name": "Promoter PV",
        "type": "SCPU",
        "status": "ACTIVE",
        "meter_ref": "InternalPVRef",
        "ownerships": [
          {
            "member_ref": "PromoterRef",
            "perc_ownership": 100
          }
        ],
        "scpu_payload": {
          "generation_capacity": 0
        }
      },
      {
        "ref": "OffTakerResourceRef",
        "name": "OffTaker House",
        "type": "IC",
        "status": "ACTIVE",
        "meter_ref": "CPEOffTakerRef",
        "ownerships": [
          {
            "member_ref": "OffTakerRef",
            "perc_ownership": 100
          }
        ],
        "ic_payload": {
          "sum_certified_power": 0,
          "ic_voltage_level": "BTN simples"
        }
      }
    ],
    "fixed_bilateral_prices": [
      {
        "provider_ref": "PromoterRef",
        "receiver_ref": "AnchorRef",
        "price": 0.07
      },
      {
        "provider_ref": "PromoterRef",
        "receiver_ref": "OffTakerRef",
        "price": 0.10
      }
    ]
  }
}

Notes¶

Promoter has no CPE — the Promoter's generation resource (SCPU) is metered by an internal meter (InternalPVRef) attached to the Anchor's CPE. No contract is needed for the Promoter.
OffTaker resource points to its CPE directly — since the OffTaker has no internal meter, meter_ref points to the CPE ref (CPEOffTakerRef), not an internal meter.
fixed_bilateral_prices are static — a single price per provider–receiver pair applies to every interval. For interval-varying prices use the bilateral prices endpoint after community creation.
Price unit — fixed_bilateral_prices.price is in €/kWh. The per-interval bilateral prices API uses €/MWh.