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

> ## Agent Instructions
> Melso MCP: https://mcp.melso.ai/mcp (OAuth; one company per connection). Documentation-search MCP: https://docs.melso.ai/mcp; it does not act on customer accounts.
>
> Use the live tool list and respect company membership. Ask the person to approve the exact invoice or tax return version in the signed-in app. Melso's professionals prepare and file included returns after approval; an AI assistant does not file. A prepared file or an approval is not evidence of filing: only the AEAT's reference and receipt are. Keep credentials out of chat and logs.

# Alta de autónomo por API — Register an autónomo

> Turn a customer about to start working into a registered autónomo: Melso files the 036 with the AEAT and the RETA alta with the Social Security.

> [!NOTE]
>
> The `alta` case is a **live capability**: Melso's professionals register
> autónomos from the Melso app today. Creating the company with its setup, the
> extra `details` fields, partner payment and the webhooks are **preview**. See
> [Availability](https://docs.melso.ai/api/availability.md).

Someone opens an account with you before they have registered as an autónomo.
With one call you hand Melso the registration; Melso's professionals file it
and your product hears when the person can start invoicing.

## What Melso does

| Administration | Filing | Result |
| - | - | - |
| AEAT | Census declaration, modelo 036: the activity and its IAE heading, the VAT regime and the income tax method | The autónomo appears in the census with their DNI or NIE as tax ID |
| Social Security (TGSS) | Alta in the RETA, with the reduced flat-rate contribution (`tarifa_plana`) when the person asks and qualifies | The resolution of the alta and the monthly contribution charged to `iban` |

The alta has no draft to approve: asking for it is the person's decision.
Melso's professionals ask through the case for anything they need, and close
it with the administrations' receipts.

## Before you start

* **Plan.** The company's plan must include the alta, or the case is sold as a
  one-off service. [List case kinds](https://docs.melso.ai/api/reference/cases/list-case-kinds.md)
  says which, under `payment`.
* **Mandates.** Melso acts before the AEAT and the TGSS under the person's
  representation: AEAT `census` and TGSS `affiliation`. The person signs them
  on a hosted page; see [Mandates](https://docs.melso.ai/api/companies.md#mandates). Signing is never a
  partner call.
* **Start date.** Send the case before `start_date`. The registration must be
  in place before the activity starts.

## The flow

**1. Create the company with its setup**

[Create a company](https://docs.melso.ai/api/reference/companies/create-company.md) of kind
`freelancer` with `setup_request` `register_autonomo` and what you already
know in `setup_details`:

```bash theme={null}
curl https://api.melso.ai/v1/companies \
  -H "Authorization: Bearer $MELSO_API_KEY" \
  -H "Idempotency-Key: cus_51907-setup" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "freelancer",
    "name": "Marta Gil Romero",
    "external_id": "cus_51907",
    "owner": {"name": "Marta Gil Romero", "email": "marta@example.com", "phone": "+34600000000", "locale": "es"},
    "fiscal_profile": {
      "tax_id": "12345678Z",
      "legal_name": "Marta Gil Romero",
      "address": "Calle de la Paz 4, 2.º B",
      "postal_code": "46003",
      "city": "València",
      "activity_type": "profesional",
      "activity_description": "Diseño gráfico para empresas"
    },
    "setup_request": "register_autonomo",
    "setup_details": {
      "start_date": "2026-12-01",
      "activity": "Diseño gráfico para empresas",
      "birth_date": "1994-05-17",
      "nuss": "281234567840",
      "clients": "Empresas en España y algún cliente de la UE",
      "tarifa_plana": "si",
      "iban": "ES9121000418450200051332"
    },
    "services": ["invoicing", "tax_returns"]
  }'
```

The response carries `setup.case_id`, the `alta` case, and `setup.missing`,
what it still needs. When nothing is missing and the plan covers it, the case
is already with Melso's professionals.

**2. Collect what is missing and the mandates**

Send the person to Melso's hosted onboarding with
[Create an onboarding link](https://docs.melso.ai/api/reference/companies/create-onboarding-link.md)
and `steps` `["setup", "mandates"]`. They complete the missing details, sign
the AEAT and TGSS mandates, and the case is sent. You receive
`mandate.signed`, then `mandate.activated` per administration.

If you collect every detail yourself, request the mandates with
[Request a mandate](https://docs.melso.ai/api/reference/mandates/create-mandate.md) and send the
person to its `signing_url`.

**3. Answer Melso's questions**

`case.information_requested` arrives when a professional needs something, for
example a copy of the DNI or which IAE heading fits best. Read the open
`information_request` with [Get a case](https://docs.melso.ai/api/reference/cases/get-case.md),
upload any file with [Upload a document](https://docs.melso.ai/api/reference/documents/upload-document.md),
and answer every item with
[Answer an information request](https://docs.melso.ai/api/reference/cases/answer-case-request.md):

```json theme={null}
{
  "request_id": "0b6f3a2e-9c1d-4e8f-a7b5-2d4c6e8f0a1b",
  "answers": [
    {"item_id": "dni", "file_id": "7e1d2c3b-4a5f-4e6d-8c7b-9a0f1e2d3c4b"},
    {"item_id": "iae", "answer": "Diseño gráfico, sin local"}
  ]
}
```

The case goes back to `review`.

**4. Hear that the autónomo is registered**

The case reaches `done` with the administration's `external_reference`, and
its documents hold the census receipt and the RETA resolution. You receive
`case.completed`, then `company.registered`: the fiscal profile's
`registration_status` is `alta` and `registered_on` is set. From here the
company is an ordinary autónomo: invoices, expenses and quarterly returns.

## A company you already have

For an autónomo who is already on your partner account, open the case
directly with [Open a case](https://docs.melso.ai/api/reference/cases/create-case.md):

```bash theme={null}
curl https://api.melso.ai/v1/companies/$COMPANY_ID/cases \
  -H "Authorization: Bearer $MELSO_API_KEY" \
  -H "Idempotency-Key: alta-cus_51907" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "alta",
    "details": {"start_date": "2026-12-01", "activity": "Diseño gráfico para empresas"},
    "note": "Quiere tarifa plana. Clientes: empresas en España.",
    "submit": true
  }'
```

`start_date` (required) and `activity` are the live contract today; send
the other details in `note` until the full `details` ship.

## Events, in order

| Event | Meaning for your product |
| - | - |
| `mandate.signed`, `mandate.activated` | Melso can act before the AEAT and the TGSS. |
| `case.updated` | The case moved, for example from `draft` to `review`. |
| `case.information_requested` | Ask the person, then answer the request. |
| `case.completed` | Filed. The receipts are on the case. |
| `company.registered` | The autónomo is registered; show them as active. |

`company.registered` carries the company:

```json theme={null}
{
  "id": "2f7a9c1e-5b3d-4e8f-a6c4-1d9b7e5f3a2c",
  "type": "company.registered",
  "created_at": "2026-11-27T11:20:05Z",
  "company_id": "9c4e2a7b-1f3d-4b6a-8e5c-0d2f4a6b8c1e",
  "data": {
    "id": "9c4e2a7b-1f3d-4b6a-8e5c-0d2f4a6b8c1e",
    "name": "Marta Gil Romero",
    "kind": "freelancer",
    "onboarded": true,
    "external_id": "cus_51907",
    "setup": {
      "request": "register_autonomo",
      "case_id": "5a1c3e7b-9d2f-4b8a-a6e4-c0f2d4b6a8e1",
      "missing": [],
      "registered_at": "2026-11-27T11:20:03Z"
    },
    "created_at": "2026-11-20T09:02:41Z"
  }
}
```

## Who pays

When the alta is sold as a one-off service, the case carries `payment_url`
and waits for the owner. Under a partner agreement you can pay it for them:
`setup_payer` `partner` on Create a company, or `payer` `partner` on Open a
case (preview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.