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

# Create embedding session

> Create a short-lived Integrations Hub session. Send only launch_url to the borrower. AMLOK captures consent and manages provider authorization and ingestion.

Create a short-lived Integrations Hub session. Send only launch\_url to the borrower. AMLOK captures consent and manages provider authorization and ingestion. All IDs and cursors must belong to the authorized workspace and environment. Required scope: connections:write.

Examples use synthetic IDs. Replace them with values returned by your environment.


## OpenAPI

````yaml openapi/amlok.json POST /v1/embedding-sessions
openapi: 3.1.0
info:
  title: AMLOK API
  version: 1.0.0
  description: >-
    AMLOK API: borrower connections, Insights origination, immutable risk
    packages and Signal monitoring. Use your institution-issued API origin.
servers: []
security:
  - BearerAuth: []
paths:
  /v1/embedding-sessions:
    post:
      tags:
        - Connections
      summary: Create embedding session
      description: >-
        Create a short-lived Integrations Hub session. Send only launch_url to
        the borrower. AMLOK captures consent and manages provider authorization
        and ingestion. All IDs and cursors must belong to the authorized
        workspace and environment. Required scope: connections:write.
      operationId: createEmbeddingSession
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
          description: >-
            Stable for one intended command and its retries, scoped to key
            workspace/environment and operation. Mismatched body returns 409.
            Full response replay 24 hours; durable receipt remains.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmbeddingSession'
            example:
              borrower_id: bor_synthetic
              embedding_version_id: embed_synthetic
              purpose: connect
              return_url: https://institution.example.com/connected
              consent_purposes:
                - credit_assessment
                - continuous_monitoring
              embed_origin: https://institution.example.com
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/EmbeddingSession'
                  meta:
                    $ref: '#/components/schemas/Meta'
                required:
                  - data
                  - meta
                additionalProperties: false
              example:
                data:
                  id: embs_synthetic
                  borrower_id: bor_synthetic
                  status: created
                  launch_url: https://borrower.example.com/session/synthetic
                  expires_at: '2026-11-06T12:15:00Z'
                  connection_ids: []
                  consent_ids: []
                  record_version: 1
                  embedding_version_id: embed_synthetic
                  purpose: connect
                  origination_id: null
                  monitor_id: null
                  requirement_id: null
                  consent_purposes:
                    - credit_assessment
                    - continuous_monitoring
                  embed_origin: https://institution.example.com
                  return_url: https://institution.example.com/connected
                  failure: null
                meta:
                  request_id: req_synthetic
                  schema_version: 1.0.0
                  environment: sandbox
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '400':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: validation_error
                  message: Validation error.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '401':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: unauthenticated
                  message: Unauthenticated.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '402':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: insufficient_credits
                  message: Insufficient credits.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '403':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: forbidden
                  message: Forbidden.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '404':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: not_found
                  message: Not found.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '409':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: idempotency_conflict
                  message: Idempotency conflict.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '410':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: cursor_expired
                  message: Cursor expired.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '413':
          description: >-
            Request exceeds the effective profile size limit or media type is
            unsupported. No command is accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: payload_too_large
                  message: payload too large
                  retryable: false
                  request_id: req_synthetic
                  field: null
        '415':
          description: >-
            Request exceeds the effective profile size limit or media type is
            unsupported. No command is accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: unsupported_media_type
                  message: unsupported media type
                  retryable: false
                  request_id: req_synthetic
                  field: null
        '422':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: validation_error
                  message: Validation error.
                  retryable: false
                  request_id: req_synthetic
                  field: null
          headers:
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '429':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: rate_limited
                  message: Rate limited.
                  retryable: true
                  request_id: req_synthetic
                  field: null
          headers:
            Retry-After:
              description: Minimum delay in seconds before retry.
              schema:
                type: integer
                minimum: 0
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
        '503':
          description: >-
            Inspect structured error; retry only when retryable. 429 and 503 can
            include Retry-After.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: '#/components/schemas/Error'
                required:
                  - error
                additionalProperties: false
              example:
                error:
                  code: temporarily_unavailable
                  message: Temporarily unavailable.
                  retryable: true
                  request_id: req_synthetic
                  field: null
          headers:
            Retry-After:
              description: Minimum delay in seconds before retry.
              schema:
                type: integer
                minimum: 0
            X-Request-ID:
              schema:
                type: string
                minLength: 1
              description: Same request ID as meta.request_id or error.request_id.
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |-
            curl --request POST --fail-with-body --max-time 30 \
              "${AMLOK_API_BASE_URL}/v1/embedding-sessions" \
              --header "Authorization: Bearer ${AMLOK_API_KEY}" \
              --header 'Accept: application/json' \
              --header 'Idempotency-Key: createEmbeddingSession-synthetic-0042' \
              --header 'Content-Type: application/json' \
              --data '{"borrower_id":"bor_synthetic","embedding_version_id":"embed_synthetic","purpose":"connect","return_url":"https://institution.example.com/connected","consent_purposes":["credit_assessment","continuous_monitoring"],"embed_origin":"https://institution.example.com"}'
        - lang: Python
          source: >
            import os

            import requests


            headers = {'Accept': 'application/json', 'Idempotency-Key':
            'createEmbeddingSession-synthetic-0042', 'Content-Type':
            'application/json'}

            headers["Authorization"] = "Bearer " + os.environ["AMLOK_API_KEY"]

            response = requests.request('POST', os.environ["AMLOK_API_BASE_URL"]
            + '/v1/embedding-sessions', headers=headers, json={'borrower_id':
            'bor_synthetic', 'embedding_version_id': 'embed_synthetic',
            'purpose': 'connect', 'return_url':
            'https://institution.example.com/connected', 'consent_purposes':
            ['credit_assessment', 'continuous_monitoring'], 'embed_origin':
            'https://institution.example.com'}, timeout=30,
            allow_redirects=False)

            response.raise_for_status()

            print(response.json())
        - lang: JavaScript
          source: >
            const headers = {"Accept": "application/json", "Idempotency-Key":
            "createEmbeddingSession-synthetic-0042", "Content-Type":
            "application/json"};

            headers.Authorization = `Bearer ${process.env.AMLOK_API_KEY}`;

            const response = await fetch(process.env.AMLOK_API_BASE_URL +
            "/v1/embedding-sessions", {
              method: "POST", headers, redirect: "error", signal: AbortSignal.timeout(30000),
              body: JSON.stringify({"borrower_id": "bor_synthetic", "embedding_version_id": "embed_synthetic", "purpose": "connect", "return_url": "https://institution.example.com/connected", "consent_purposes": ["credit_assessment", "continuous_monitoring"], "embed_origin": "https://institution.example.com"})
            });

            if (!response.ok) throw new Error(`HTTP ${response.status}: ${await
            response.text()}`);

            console.log(await response.json());
components:
  schemas:
    CreateEmbeddingSession:
      type: object
      properties:
        borrower_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        embedding_version_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        purpose:
          type: string
          enum:
            - connect
            - reauthorize
          description: >-
            Purpose for CreateEmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        connection_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        return_url:
          type: string
          minLength: 1
          description: >-
            Must match an institution-approved return URL. No arbitrary
            redirects.
          format: uri
        origination_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        consent_purposes:
          type: array
          items:
            type: string
            enum:
              - credit_assessment
              - continuous_monitoring
          minItems: 1
          uniqueItems: true
          description: >-
            Explicit purposes presented for borrower authorization; must be a
            subset of the published Hub purposes. Credit assessment alone does
            not permit monitoring.
        embed_origin:
          type: string
          minLength: 1
          description: >-
            Exact HTTPS parent origin approved for this Hub. Omit for full-page
            redirects. No path, wildcard or opaque origin.
          format: uri
        monitor_id:
          type: string
          minLength: 1
          description: >-
            Monitor whose open requirement this session addresses. Mutually
            exclusive with origination_id.
        requirement_id:
          type: string
          minLength: 1
          description: >-
            Open requirement on origination_id or monitor_id; completion
            atomically associates the authorized connection with that resource.
      required:
        - borrower_id
        - embedding_version_id
        - purpose
        - return_url
        - consent_purposes
      additionalProperties: false
      allOf:
        - if:
            properties:
              purpose:
                const: reauthorize
          then:
            required:
              - connection_id
          else:
            not:
              required:
                - connection_id
        - not:
            required:
              - origination_id
              - monitor_id
        - if:
            required:
              - requirement_id
          then:
            oneOf:
              - required:
                  - origination_id
              - required:
                  - monitor_id
        - if:
            anyOf:
              - required:
                  - origination_id
              - required:
                  - monitor_id
          then:
            required:
              - requirement_id
      description: >-
        Launch an already published console-configured Hub for this borrower.
        Enabled integrations and categories come from embedding_version_id and
        cannot be overridden here. The backend verifies its own borrower
        association before creating a session; only the short-lived launch URL
        reaches the browser.
    EmbeddingSession:
      type: object
      properties:
        id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        borrower_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        status:
          type: string
          enum:
            - created
            - in_progress
            - completed
            - expired
            - failed
            - cancelled
          description: >-
            Current lifecycle state. See the product lifecycle and recovery
            guides.
        launch_url:
          anyOf:
            - type: string
              minLength: 1
              description: Short-lived borrower session, never an institution API key.
              format: uri
            - type: 'null'
          description: >-
            Short-lived borrower capability URL. Use in a permitted iframe or
            full-page navigation; never log or persist it as a reusable
            integration credential.
        expires_at:
          type: string
          minLength: 1
          format: date-time
          description: UTC expiration; do not use this resource after this instant.
        connection_ids:
          type: array
          items:
            type: string
            minLength: 1
            description: >-
              Opaque identifier, authorized within the API key workspace and
              environment.
          uniqueItems: true
          description: >-
            Connection ids for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        consent_ids:
          type: array
          items:
            type: string
            minLength: 1
            description: >-
              Opaque identifier, authorized within the API key workspace and
              environment.
          uniqueItems: true
          description: >-
            Consent ids for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        embedding_version_id:
          type: string
          minLength: 1
          description: Published Hub configuration version used by this session.
        purpose:
          type: string
          enum:
            - connect
            - reauthorize
          description: >-
            Purpose for EmbeddingSession. Constraints, requiredness and allowed
            values are defined by this schema.
        origination_id:
          anyOf:
            - type: string
              minLength: 1
              description: Opaque ID within the authorized workspace and environment.
            - type: 'null'
          description: >-
            Origination id for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        monitor_id:
          anyOf:
            - type: string
              minLength: 1
              description: Opaque identifier in the authorized workspace and environment.
            - type: 'null'
          description: >-
            Monitor id for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        requirement_id:
          anyOf:
            - type: string
              minLength: 1
              description: Opaque identifier in the authorized workspace and environment.
            - type: 'null'
          description: >-
            Requirement id for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        consent_purposes:
          type: array
          items:
            type: string
            enum:
              - credit_assessment
              - continuous_monitoring
          minItems: 1
          uniqueItems: true
          description: >-
            Consent purposes for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        embed_origin:
          anyOf:
            - type: string
              minLength: 1
              format: uri
            - type: 'null'
          description: >-
            Embed origin for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        return_url:
          type: string
          minLength: 1
          format: uri
          description: >-
            Return url for EmbeddingSession. Constraints, requiredness and
            allowed values are defined by this schema.
        failure:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
          description: >-
            Failure for EmbeddingSession. Constraints, requiredness and allowed
            values are defined by this schema.
        record_version:
          type: integer
          minimum: 1
          description: >-
            Monotonic version for this resource; compare with
            event.resource_version.
      required:
        - id
        - borrower_id
        - status
        - launch_url
        - expires_at
        - connection_ids
        - consent_ids
        - embedding_version_id
        - purpose
        - origination_id
        - monitor_id
        - requirement_id
        - consent_purposes
        - embed_origin
        - return_url
        - failure
        - record_version
      additionalProperties: false
      description: >-
        Completion means the connection journey completed, not that source
        ingestion or underwriting completed. URLs are returned only to
        authorized callers; never send in events.
    Meta:
      type: object
      properties:
        request_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        schema_version:
          type: string
          minLength: 1
          description: >-
            Schema version for Meta. Constraints, requiredness and allowed
            values are defined by this schema.
        environment:
          type: string
          enum:
            - sandbox
            - live
          description: >-
            Environment for Meta. Constraints, requiredness and allowed values
            are defined by this schema.
      required:
        - request_id
        - schema_version
        - environment
      additionalProperties: false
    Error:
      type: object
      properties:
        code:
          type: string
          enum:
            - validation_error
            - unauthenticated
            - forbidden
            - not_found
            - invalid_state
            - idempotency_conflict
            - insufficient_credits
            - precondition_failed
            - cursor_expired
            - rate_limited
            - temporarily_unavailable
            - deal_snapshot_conflict
            - payload_too_large
            - unsupported_media_type
            - document_rejected
            - processing_failed
            - session_expired
            - consent_purpose_missing
            - sandbox_only
            - scenario_not_available
            - idempotency_result_expired
          description: >-
            Code for Error. Constraints, requiredness and allowed values are
            defined by this schema.
        message:
          type: string
          minLength: 1
          description: >-
            Message for Error. Constraints, requiredness and allowed values are
            defined by this schema.
        retryable:
          type: boolean
          description: >-
            Retryable for Error. Constraints, requiredness and allowed values
            are defined by this schema.
        request_id:
          type: string
          minLength: 1
          description: >-
            Opaque identifier, authorized within the API key workspace and
            environment.
        field:
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
          description: >-
            Field for Error. Constraints, requiredness and allowed values are
            defined by this schema.
      required:
        - code
        - message
        - retryable
        - request_id
        - field
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Server-to-server API key bound to exactly one workspace, institution
        tenant and environment. No caller-supplied workspace override is
        accepted. Do not use in public browser code.

````

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