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

# Activate Connection

> Request activation for one or more connections of an app.

Requests activation for the connections of one or more providers in one call. Each entry in `activations` becomes one submission that covers the listed connections of one provider. The connections in a submission share one status and activate together. See [Activate Connections](https://docs.hopae.com/v2/guides/concepts/connections/activation.md).

## Headers

**Authorization** `string` *required*

`Bearer sk_workspace_...`, a Workspace API key of the organization that owns the app. See [Workspace API](https://docs.hopae.com/v2/api-reference/workspace/introduction.md).

**Content-Type** `string` *required* (default: application/json)

Must be `application/json`.

**Idempotency-Key** `string`

A unique key for this request, up to 255 characters. If you retry with the same key and the same body within 24 hours, you get the stored response with `Idempotency-Replayed: true`, and nothing is submitted twice. See [Request behavior](https://docs.hopae.com/v2/api-reference/workspace/introduction.md#request-behavior).

## Path Parameters

**appId** `string` *required*

The app ID returned by Create App or List Apps.

## Request Body

**activations** `object[]` *required*

One entry per provider submission, with at least one entry.

**properties**

**providerId** `string` *required*

The provider to submit for: `provider.id` from [List App Connections](https://docs.hopae.com/v2/api-reference/workspace/get-providers.md), for example `smart-id`.

**connectionIds** `string[]`

The catalog connection IDs to activate under this provider: `id` from List App Connections. IDs that are unknown or belong to another provider are skipped. IDs that the app's environment doesn't support, IDs already activated for the app, and `contract` connections on a production app are also skipped when another ID in the entry is accepted. When none is, the entry fails with the matching `error`. If you omit the list or send `[]`, the entry fails with `validation_invalid_parameter`; it never means all of the provider's connections.

**fields** `object`

The registration form for this submission: a map from requirement `id` to a string or boolean value. Read the requirements from `activationProcess.requirements` in List App Connections. Omit it when the activation method is `direct`.

**persist** `boolean` (default: false)

If `true`, the app-wide fields of each accepted registration, such as company name and contact details, are also saved on the app. They then appear as `currentValue` for other providers. Provider-specific fields are not saved. If `false`, the fields are stored only with the submission.

## How submissions are handled

The result of each entry depends on the connection's activation method and the app's environment:

| Method | Sandbox app | Production app |
| :- | :- | :- |
| `direct` | `activated` in this response | `activated` in this response |
| `registration` | `requested`. Finish it with [Instant Activate](https://docs.hopae.com/v2/api-reference/workspace/instant-activate.md) | `requested`. Hopae reviews it and activates it |
| `contract` | `activated` in this response | Refused with `contract_activation_required` |

> [!NOTE]
>
> On a sandbox app, a `registration` submission stays `requested`. Call [Instant Activate](https://docs.hopae.com/v2/api-reference/workspace/instant-activate.md) with its `activationInstanceId` to activate it right away.

A `registration` entry with a missing required field is still filed, with `status: "rejected"` and `rejection.reason: "missing_required_fields"`. A `select` value outside its options is filed the same way with `rejection.reason: "invalid_value"`. Fix the fields and submit again.

Newly activated connections are enabled only in workflows that have **Automatically enable newly activated connections** turned on, and only in display groups that have no enabled connection yet.

## Response

`200 OK`, even when some entries fail. Check every entry in `results`.

**results** `object[]` *required*

One result per entry in `activations`, in the same order. A result has either `activationInstanceId` and `status` (the submission was filed) or `error` (nothing was filed).

**properties**

**providerId** `string` *required*

The `providerId` you sent.

**connectionIds** `string[]` *required*

For a filed submission, the connections it covers, without the skipped IDs. For an `error` result, the IDs you sent.

**activationInstanceId** `string`

Present only when the submission was filed. The submission ID (`act_…`), also listed under `instances` in List App Connections.

**status** `string`

Present only when the submission was filed: `activated`, `requested`, or `rejected`.

**rejection** `object`

Present only when `status` is `rejected`. `reason` is `missing_required_fields` (with `missingFields`, the requirement IDs that were missing or empty) or `invalid_value` (with `message`).

**error** `object`

Present only when the entry was refused and nothing was filed.

**properties**

**code** `string` *required*

* `contract_activation_required`: the connections need a contract on a production app. Contact the address in `contact`.
* `validation_invalid_parameter`: unknown `providerId`, no `connectionIds`, none of the IDs is a connection of this provider, or the connections are not available in the app's environment.
* `already_activated`: every requested connection is already activated for the app.

**message** `string` *required*

A human-readable explanation.

**contact** `string`

Present only with `contract_activation_required`. The support email address to contact.

## Errors

These errors apply to the whole request. Besides the authentication and subscription errors that every route can return (see [Workspace API](https://docs.hopae.com/v2/api-reference/workspace/introduction.md#authentication-and-base-url)), this endpoint returns:

| HTTP | Code | When |
| :- | :- | :- |
| 400 | `VALIDATION_INVALID_PARAMETER` | `activations` is missing, empty, or not an array, or an entry is malformed (for example `providerId` is missing). `persist` is not a boolean. `Idempotency-Key` is longer than 255 characters |
| 403 | `AUTH_FORBIDDEN` | The app belongs to another organization |
| 404 | `RESOURCE_NOT_FOUND` | Unknown app, or the app was deleted |
| 409 | `IDEMPOTENCY_KEY_CONFLICT` | The `Idempotency-Key` was used before with a different body |
| 409 | `IDEMPOTENCY_REQUEST_IN_PROGRESS` | An earlier request with the same `Idempotency-Key` is still running |

```bash cURL theme={null}
curl --request POST \
  --url 'https://api.hopae.com/connect/v2/apps/{appId}/connections/activate' \
  --header 'Authorization: Bearer sk_workspace_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "activations": [
      {
        "providerId": "smart-id",
        "connectionIds": ["smart-id"],
        "fields": {
          "legalCompanyName": "Acme Corporation B.V.",
          "registrationNumber": "12345678",
          "registeredAddress": "1 Example Street, Amsterdam, Netherlands",
          "displayName": "Acme"
        }
      },
      {
        "providerId": "fi-ftn",
        "connectionIds": ["fi-ftn"]
      }
    ],
    "persist": true
  }'
```

```json theme={null}
{
  "results": [
    {
      "providerId": "smart-id",
      "connectionIds": ["smart-id"],
      "activationInstanceId": "act_01JBX5N8Q2W7RZ3K4M6P9T1V0C",
      "status": "requested"
    },
    {
      "providerId": "fi-ftn",
      "connectionIds": ["fi-ftn"],
      "error": {
        "code": "contract_activation_required",
        "message": "This provider requires a contract. Contact support to proceed.",
        "contact": "support@hopae.com"
      }
    }
  ]
}
```


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