> For the complete documentation index, see [llms.txt](https://flapjax.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://flapjax.gitbook.io/docs/rest-api/guides/automatic-data-creation.md).

# Automatic Data Creation

Systemic data pushes

When you create or update a person or record with relationship attributes, the API checks whether the referenced entities exist. If they don't, the API **automatically creates them** so the relationship link is always valid.

## How It Works

{% stepper %}
{% step %}
You send a request that includes a relationship attribute — for example, setting a "customer" attribute to `"user-001"`.
{% endstep %}

{% step %}
The API normalises the value (see [Attribute Normalization](/docs/rest-api/guides/reference-normalisation.md)) and looks up the referenced entity.
{% endstep %}

{% step %}
If the entity **exists**, the relationship is linked normally.
{% endstep %}

{% step %}
If the entity **does not exist**, the API creates a minimal placeholder entity with just the external ID, then links the relationship.

This happens transparently — you don't need to pre-create referenced entities before setting up relationships.
{% endstep %}
{% endstepper %}

## What Gets Auto-Created

The type of entity created depends on the attribute:

* **Person-type attributes**: A new person is created with the given external ID and no other fields populated.
* **Stack-type attributes**: A new record is created in the target stack with the given external ID and no other attribute values.

## Example

You create a record in the "orders" stack and set its "customer" attribute to a person that doesn't exist yet:

```bash
curl -X POST https://your-domain/v1/stacks/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order-001",
    "customer": "new-user-123"
  }'
```

The API will:

{% stepper %}
{% step %}
Create the order record with external ID `order-001`.
{% endstep %}

{% step %}
Look up a person with external ID `new-user-123`.
{% endstep %}

{% step %}
Since `new-user-123` doesn't exist, create a new person with that external ID.
{% endstep %}

{% step %}
Link the "customer" relationship from the order to the newly created person.
{% endstep %}
{% endstepper %}

You can later update the auto-created person with additional details (name, email, etc.) using the People endpoints.

## Enrichment

When an auto-created entity is later updated with more data, the existing relationships remain intact. This pattern is called **enrichment;** you can set up relationships first and fill in details later.