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

# Get Activation Steps

> Retrieve the computed activation steps for a specific provider.

Returns the activation steps, current progress, and overall state for a provider. Steps vary by provider.

## Request

<ParamField header="Authorization" type="string" required>
  `Bearer <API_KEY>` from Console > Developers > Workspace API Keys.
</ParamField>

### Path parameters

<ParamField path="client_id" type="string" required>
  Client identifier of the app.
</ParamField>

<ParamField path="provider_id" type="string" required>
  Provider identifier (e.g., `smartid`, `ftn`, `mitid`).
</ParamField>

## Response

<ResponseField name="providerId" type="string">
  Echo of the provider identifier from the request path.
</ResponseField>

<ResponseField name="state" type="string">
  Overall activation state: `not_started`, `in_progress`, or `completed`.
</ResponseField>

<ResponseField name="currentStepIndex" type="number">
  Zero-based index of the first incomplete step. Equals the last step index when all steps are completed.
</ResponseField>

<ResponseField name="steps" type="object[]">
  Ordered list of activation steps. Each step contains:

  <Expandable title="Step object">
    <ResponseField name="type" type="string">
      Step identifier: `enable`, `activation-form`, `upload`, `api-key`, or `activated`.
    </ResponseField>

    <ResponseField name="title" type="string">
      Human-readable step title.
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable step description. For the `activation-form` step, this is overridden on contract-category providers to describe the out-of-band follow-up.
    </ResponseField>

    <ResponseField name="contractProvider" type="boolean">
      *(activation-form step, contract providers only)* Present and `true` when the provider requires a direct contract with the upstream provider. Signals that clearing the `activation-form` step does not auto-advance activation — the Hopae team reaches out via the submitted `contactEmail` to finalize the contract. Use this flag to branch your UI between "self-service" and "awaiting Hopae follow-up" messaging.
    </ResponseField>

    <ResponseField name="requiredFields" type="object[]">
      *(activation-form step only)* List of required fields for the activation form.

      <Expandable title="Field object">
        <ResponseField name="label" type="string">Display label.</ResponseField>
        <ResponseField name="name" type="string">Field key used in the `data` object of the submit request body.</ResponseField>
        <ResponseField name="value" type="string | boolean">Current value, or empty string if not yet provided.</ResponseField>
        <ResponseField name="type" type="string">Data type of the value: `string`, `base64` (for image/logo fields), `email`, `url`, or `boolean`.</ResponseField>

        <ResponseField name="example" type="string">
          Example value illustrating the expected format (e.g., `"HRB 123456"`).
        </ResponseField>

        <ResponseField name="helpText" type="string">
          Short guidance shown to the user explaining what the field expects.
        </ResponseField>

        <ResponseField name="validationRegex" type="string">
          *(Optional, advisory)* Regex hint for client-side validation. Not currently enforced server-side — rely on `type` and `options` for authoritative checks.
        </ResponseField>

        <ResponseField name="options" type="object[]">
          *(Optional)* Allowed values when the field is an enum.

          <Expandable title="Option object">
            <ResponseField name="value" type="string | boolean">Option value.</ResponseField>
            <ResponseField name="description" type="string">Option description.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="form" type="object | null">
      *(activation-form step only)* Previously submitted form details, or `null` if no form has been submitted yet.

      <Expandable title="Form object">
        <ResponseField name="id" type="string">Unique identifier of the submitted form.</ResponseField>

        <ResponseField name="status" type="string">
          Customer-facing review status: `submitted` (form received and under review — internal `processing` and `completed` states are collapsed to this) or `rejected` (admin rejected the submission). A `rejected` form can be resubmitted via [Submit Activation Form](/api-reference/workspace/activation/submit-activation-form). Approval is detected by `currentStepIndex` advancing past the `activation-form` step, not by a change in `form.status`.
        </ResponseField>

        <ResponseField name="note" type="string">
          Note attached to the form. Initially carries any user-submitted note; after an admin decision, this is overwritten with the admin's note (e.g., the rejection reason). Empty string if no note has been set.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="documents" type="object[]">
      *(upload step only)* Catalog of documents the provider requires. Each entry has a `label` describing the document and, where a template is available, a `templateUrl` to download the form to fill in. An `optional: true` flag marks documents that are not required for the step to complete.
    </ResponseField>

    <ResponseField name="uploaded" type="object[]">
      *(upload step only)* Documents already uploaded against this provider, including their review state. Rejected uploads are retained here (rather than deleted) so clients can surface the reviewer's rejection note; re-uploading a replacement supersedes them for step-progression purposes.

      <Expandable title="Uploaded document object">
        <ResponseField name="documentId" type="string">Unique identifier of the uploaded document.</ResponseField>
        <ResponseField name="fileName" type="string">Original file name as submitted.</ResponseField>
        <ResponseField name="fileSize" type="number">Size of the file in bytes.</ResponseField>
        <ResponseField name="contentType" type="string">MIME type (e.g., `application/pdf`).</ResponseField>
        <ResponseField name="uploadedAt" type="string">ISO 8601 upload timestamp.</ResponseField>

        <ResponseField name="state" type="string">
          Review state: `pending`, `processed`, or `rejected`. The `upload` step advances once the count of non-`rejected` uploads reaches the number of required entries in `documents`. Rejected uploads do not count toward that total — re-upload a replacement via [Upload Activation Documents](/api-reference/workspace/activation/upload-documents) to move past a rejection.
        </ResponseField>

        <ResponseField name="documentType" type="string">*(Optional)* Catalog entry the upload corresponds to (matches a `documents[].label`). Populated only for uploads originated from the Hopae Console; absent for uploads made through this Workspace API — correlate by `fileName` instead.</ResponseField>
        <ResponseField name="note" type="string">Review note from the Hopae team. After a rejection, this contains the reviewer's reason.</ResponseField>
        <ResponseField name="reviewedAt" type="string">ISO 8601 timestamp of the most recent review decision, if any.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -H "Authorization: Bearer sk_workspace_test_..." \
    "https://sandbox.api.hopae.com/connect/v1/apps/abc123/providers/spid-ig/activation/steps"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "providerId": "spid-ig",
    "state": "in_progress",
    "currentStepIndex": 3,
    "steps": [
      {
        "type": "enable",
        "title": "Enable Provider",
        "description": "Enable this provider to proceed to the next steps."
      },
      {
        "type": "activation-form",
        "title": "Submit Activation Request Form",
        "description": "Submit the required information for provider activation.",
        "requiredFields": [
          {
            "label": "Legal Company Name",
            "name": "legalCompanyName",
            "value": "Acme Corp",
            "type": "string",
            "example": "Acme Corporation Ltd.",
            "helpText": "The registered legal name of the company, as shown on official incorporation documents."
          },
          {
            "label": "Registered Address",
            "name": "registeredAddress",
            "value": "9 Boulevard Prince Henri, L-1724 Luxembourg",
            "type": "string",
            "example": "9 Boulevard Prince Henri, L-1724 Luxembourg",
            "helpText": "Full registered business address including street, city, postal code, and country."
          },
          {
            "label": "VAT Number",
            "name": "vatNumber",
            "value": "LU12345678",
            "type": "string",
            "example": "DE123456789",
            "helpText": "The EU VAT identification number, including the country prefix."
          },
          {
            "label": "Registration Number",
            "name": "registrationNumber",
            "value": "12345678",
            "type": "string",
            "example": "B123456",
            "helpText": "The company registration number from your country's business registry (e.g., RCS Luxembourg, HRB Germany, CVR Denmark)."
          },
          {
            "label": "Service Description",
            "name": "serviceDescription",
            "value": "Customer identity verification for KYC onboarding.",
            "type": "string",
            "example": "Acme IDV console — customer identity verification for KYC onboarding.",
            "helpText": "One-sentence description of your service, shown during provider activation review."
          },
          {
            "label": "User Data Level",
            "name": "userDataLevel",
            "value": "basic",
            "type": "string",
            "options": [
              {
                "value": "basic",
                "description": "Basic: name, surname, fiscal code, and date of birth"
              },
              {
                "value": "advanced",
                "description": "Advanced: all basic attributes plus place of birth, gender, ID document details, phone number, email, and registered address"
              }
            ],
            "helpText": "Italian SPID data retrieval scope. 'basic' is sufficient for age/identity verification; 'advanced' adds place of birth and document details."
          },
          {
            "label": "Logo",
            "name": "logo",
            "value": "data:image/png;base64,iVBORw0KGgo...",
            "type": "base64",
            "example": "data:image/png;base64,iVBORw0KGgo...",
            "helpText": "Base64-encoded PNG or SVG logo (max 256KB). Used for branding in provider-facing consent screens."
          },
          {
            "label": "Contact Email",
            "name": "contactEmail",
            "value": "compliance@acme.com",
            "type": "email",
            "example": "ops@acme.com",
            "helpText": "Operations contact email — Hopae will use this for activation status notifications."
          }
        ],
        "form": {
          "id": "fe1ce6d9-90fb-4f42-88ae-4622135c7f19",
          "status": "submitted",
          "note": ""
        }
      },
      {
        "type": "upload",
        "title": "Upload Documents",
        "description": "Upload the required documents for provider activation.",
        "documents": [
          {
            "label": "SPID Aggregation Agreement",
            "templateUrl": "https://static.hopae.com/templates/spid-ig/spid_aggregation_agreement.docx"
          }
        ],
        "uploaded": [
          {
            "documentId": "0567eeb3-eda7-489a-9ba8-84f0ae3f301e",
            "fileName": "spid_aggregation_agreement.docx",
            "fileSize": 784044,
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
            "uploadedAt": "2026-04-20T02:20:27.521Z",
            "state": "pending"
          }
        ]
      },
      {
        "type": "api-key",
        "title": "Issuing Production API Key",
        "description": "Production API keys are being issued."
      },
      {
        "type": "activated",
        "title": "Provider Activated",
        "description": "API key has successfully been issued and configured."
      }
    ]
  }
  ```
</ResponseExample>