Activate Connection

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
  }'

{
  "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"
      }
    }
  ]
}

POST

connect

apps

{appId}

connections

activate

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
  }'

{
  "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"
      }
    }
  ]
}

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.

Headers

string

required

Bearer sk_workspace_..., a Workspace API key of the organization that owns the app. See Workspace API.

string

default:"application/json"

required

Must be application/json.

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.

Path Parameters

string

required

The app ID returned by Create App or List Apps.

Request Body

object[]

required

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

Show properties

string

required

The provider to submit for: provider.id from List App Connections, for example smart-id.

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.

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.

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	`requested`. Hopae reviews it and activates it
`contract`	`activated` in this response	Refused with `contract_activation_required`

On a sandbox app, a registration submission stays requested. Call Instant Activate 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.

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).

Show properties

string

required

The providerId you sent.

string[]

required

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

string

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

string

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

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).

object

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

Show properties

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.

string

required

A human-readable explanation.

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), 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

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
  }'

{
  "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"
      }
    }
  ]
}

Overview

Apps

Connections

Redirect URIs

Activate Connection

Headers

Path Parameters

Request Body

How submissions are handled

Response

Errors

​Headers

​Path Parameters

​Request Body

​How submissions are handled

​Response

​Errors

Headers

Path Parameters

Request Body

How submissions are handled

Response

Errors