Bynn Intelligence Autodoc API

openapi: 3.2.0
info:
  title: BYNN Autodoc API
  description: 'The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Use your **Private API Key**, which looks like `private_xxxxxxxxxxxxxxxxxxxxxxxx` (or `private_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx` for a sandbox key), as the username in HTTP Basic auth with an empty password, or send it as `Authorization: Bearer `. Your keys are at https://dashboard.bynn.com/integration.'
  termsOfService: https://bynn.com/terms
  contact:
    name: BYNN Development Team
    email: hello@bynn.com
    url: https://docs.bynn.com
  license:
    name: BYNN Documentation
    url: https://docs.bynn.com
  version: '1.0'
servers:
- url: https://api.bynn.com/v1
tags:
- name: autodoc
  description: Operations about autodocs
paths:
  /autodoc/invitations/locales:
    get:
      summary: List supported invitation locales
      description: 'Returns the list of IETF language tags supported as the `locale` parameter on POST /v1/autodoc/invitations.


        Each entry has a `code` (the value to send) and a `name` (a human-readable label rendered in the requesting user''s locale where available, falling back to the uppercased code).'
      security:
      - PrivateKey: []
      - JwtAuth: []
      responses:
        '200':
          description: List supported invitation locales
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - autodoc
      operationId: getAutodocInvitationsLocales
  /autodoc/invitations:
    get:
      summary: List AutoDoc invitations
      description: 'Returns a paginated list of AutoDoc invitations belonging to the authenticated organization. Results are ordered by creation date, newest first.


        **Filtering.** All filter parameters are optional and combine with AND semantics. Use `reference` to look up invitations you previously created with a specific customer-defined identifier (e.g. your CRM customer ID). Use `search` for partial matches on the recipient email or phone (case-insensitive). Use `workflow_token`, `status`, or `channel` to narrow the result set. Use `date_from` / `date_to` to constrain creation time.


        **Pagination.** Default page size is 20, maximum 100. Use `page` (1-indexed) and `per_page` to navigate. Response includes a `pagination` object with `total`, `totalPages`, `page`, and `perPage`.'
      parameters:
      - in: query
        name: page
        description: Page number (1-indexed). Defaults to 1.
        required: false
        example: 1
        schema:
          type: integer
          format: int32
          default: 1
      - in: query
        name: per_page
        description: Items per page. Min 1, max 100. Defaults to 20.
        required: false
        example: 20
        schema:
          type: integer
          format: int32
          minimum: 1
          maximum: 100
          default: 20
      - in: query
        name: workflow_token
        description: Filter by workflow token (e.g. wf_xxx). Returns only invitations created against this workflow.
        required: false
        example: wf_ULA5NSu9pRsUctA9DBmkRQya
        schema:
          type: string
      - in: query
        name: status
        description: Filter by lifecycle status.
        required: false
        example: sent
        schema:
          type: string
          enum:
          - pending
          - sent
          - delivered
          - opened
          - started
          - failed
          - completed
          - rejected
      - in: query
        name: channel
        description: Filter by delivery channel.
        required: false
        example: email
        schema:
          type: string
          enum:
          - email
          - sms
      - in: query
        name: reference
        description: Exact-match filter on the customer-defined reference. Use to look up invitations by your own customer ID, order number, or other external identifier.
        required: false
        example: cust_42891
        schema:
          type: string
      - in: query
        name: date_from
        description: Filter to invitations created on or after this timestamp (ISO 8601).
        required: false
        example: '2026-04-01T00:00:00Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: date_to
        description: Filter to invitations created on or before this timestamp (ISO 8601).
        required: false
        example: '2026-04-30T23:59:59Z'
        schema:
          type: string
          format: date-time
      - in: query
        name: search
        description: Case-insensitive partial match against the recipient field (email or phone). Special LIKE characters are escaped. Minimum 3 characters required to avoid full-table scans.
        required: false
        example: jane
        schema:
          type: string
      security:
      - PrivateKey: []
      - JwtAuth: []
      responses:
        '200':
          description: List AutoDoc invitations
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - autodoc
      operationId: getAutodocInvitations
    post:
      summary: Send an AutoDoc invitation
      description: 'Sends an invitation to a recipient (by email or SMS) to start a specific AutoDoc workflow. The recipient receives a link that opens the AutoDoc visitor app and begins the workflow with their identity already attached to the resulting dossier.


        **Lifecycle.** A new invitation is created with `status: pending`. A background delivery job is enqueued immediately; once the channel provider has accepted the message, status flips to `sent` and `sentAt` is populated. Subsequent provider-side events advance status through `delivered`, `opened`, and `started`. If delivery fails permanently the invitation is marked `failed` and `errorMessage` is populated.


        **Link expiration.** Invitation links are valid for 30 days from creation. After expiration the link returns an error to the recipient. There is no automatic resend — create a new invitation if needed.


        **Channel-specific behavior.**

        - `email`: a branded HTML email is sent to `recipient`. Use a valid email address. Emails are sent from `@auto-doc.ai` with your organization name as the display name (e.g. `Acme Corp `).

        - `sms`: a short message containing the start URL is sent to `recipient`. Use E.164 (`+15551234567`) or international format. Loose validation accepts most readable phone formats.


        **Idempotency.** This endpoint is **not** idempotent — repeated calls create new invitations. If you need de-duplication, send a unique `reference` and check `GET /v1/autodoc/invitations?reference=...` before retrying.


        **Recipient URL shape.** The link delivered to the recipient is:

        `https://start.auto-doc.ai/?invitation_token=`

        The invitation token in the query string lets the visitor app correlate the resulting dossier with this invitation.


        **Localization.** Set `locale` to one of the supported language codes to send the email or SMS in that language. Supported codes are returned by `GET /v1/autodoc/invitations/locales`. Defaults to the organization''s default locale or English.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postAutodocInvitations'
        required: true
      security:
      - PrivateKey: []
      - JwtAuth: []
      responses:
        '201':
          description: Send an AutoDoc invitation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_AutoDocInvitation'
        '400':
          description: invalid_request_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '402':
          description: insufficient_balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '404':
          description: workflow_not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '422':
          description: validation_error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '429':
          description: rate_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - autodoc
      operationId: postAutodocInvitations
  /autodoc/invitations/{token}:
    get:
      summary: Get an AutoDoc invitation
      description: 'Returns a single invitation by its token. Use this endpoint to poll the lifecycle status of an invitation you previously created — `status` advances through `pending` → `sent` → `delivered` → `opened` → `started` as the recipient interacts with the link.


        **Lookup.** The `:token` segment accepts either the prefixed form (`adi_xxx`) or the raw token. The endpoint returns 404 if the invitation does not exist or belongs to a different organization (no existence leak across tenants).'
      parameters:
      - in: path
        name: token
        description: Invitation token (adi_xxx).
        required: true
        example: adi_abc123def456
        schema:
          type: string
      security:
      - PrivateKey: []
      - JwtAuth: []
      responses:
        '200':
          description: Get an AutoDoc invitation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_AutoDocInvitation'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - autodoc
      operationId: getAutodocInvitationsToken
  /autodoc/invitations/{token}/resend:
    post:
      summary: Resend an invitation
      description: 'Re-dispatches the email or SMS for an invitation that was previously sent. Use this when the recipient never received the original (filtered, deleted, or wrong inbox) and asks for a copy.


        **What resend does.** Flips the invitation status from `sent` back to `pending`, clears `sentAt`, and enqueues a fresh delivery via the same job pipeline that handled the original send. Status will move `pending` → `sent` again as soon as the channel provider accepts the message. If the linked dossier already exists (recipient had partially started before), the link is preserved — only the delivery layer is re-fired.


        **Eligibility.** Only invitations in `sent` status can be resent. Other statuses are rejected:

        - `pending`: original delivery is still in flight; wait for it to settle.

        - `delivered`, `opened`, `started`, `completed`, `rejected`: the recipient has already engaged; resending would create confusion.

        - `failed`: handled by the delivery job''s automatic retry — see invitation lifecycle.


        **Expiration.** Expired invitations cannot be resent. Create a new invitation instead.


        **Per-invitation limits.**

        - **Maximum 10 send attempts** per invitation (initial send + each successful resend). Once `deliveryAttempts` reaches 10, this endpoint returns 422 `max_attempts_reached`. Create a new invitation to continue contacting the recipient.

        - **3-minute cooldown** between sends. Resending within 3 minutes of `sentAt` returns 429 `cooldown_active` with a `remaining_seconds` hint in the error message.


        **Billing.** Resends are billed at the same rate as the original send (`send.email` for email, `send.sms` for SMS). Test private keys (the test counterpart of a live key) are not billed.


        **Authentication.** Both `JwtAuth` and `PrivateKey` are accepted. Per-IP throttle: 30 requests per minute. Per-organization throttle: 20 resends per minute (separate bucket from invitation creation).'
      parameters:
      - in: path
        name: token
        description: Invitation token (adi_xxx).
        required: true
        example: adi_abc123def456
        schema:
          type: string
      security:
      - PrivateKey: []
      - JwtAuth: []
      responses:
        '201':
          description: Resend an invitation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_AutoDocInvitation'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '402':
          description: insufficient_balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '404':
          description: not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '422':
          description: invalid_state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '429':
          description: rate_limit_exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - autodoc
      operationId: postAutodocInvitationsTokenResend
components:
  schemas:
    postAutodocInvitations:
      type: object
      properties:
        workflowToken:
          type: string
          description: Workflow token (e.g. wf_xxx) to start when the recipient opens the invitation link.
          example: wf_ULA5NSu9pRsUctA9DBmkRQya
        channel:
          type: string
          description: Delivery channel — "email" or "sms".
          enum:
          - email
          - sms
          example: email
        recipient:
          type: string
          description: Email address (when channel=email) or phone number in E.164 or international format (when channel=sms). Max 255 characters.
          example: jane.doe@example.com
        reference:
          type: string
          description: Customer-defined identifier (customer number, UUID, order number, etc.) for cross-referencing this invitation back to your own system. Returned verbatim on the invitation entity. Max 255 characters.
          example: cust_42891
        locale:
          type: string
          description: IETF language tag for the recipient-facing email/SMS content. See GET /v1/autodoc/invitations/locales for supported values. Defaults to the organization default locale, or English if unset.
          example: en
      required:
      - workflowToken
      - channel
      - recipient
      description: Send an AutoDoc invitation
    Bynn_V1_Entities_Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: validation_error
              description: Type of error
            message:
              type: string
              example: Invalid parameters
              description: Error message
            reason:
              type: string
              example: issuer_key_unavailable
              description: Machine-readable cause, where one is set
            retry_after:
              type: integer
              format: int32
              example: 60
              description: Seconds to wait before retrying
            limit:
              type: integer
              format: int32
              example: 30
              description: The limit that was exceeded
            detail:
              type: string
              description: Operator-facing detail, outside production
          required:
          - type
          - message
      required:
      - error
      description: Bynn_V1_Entities_Error model
    Bynn_V1_Entities_AutoDocInvitation:
      type: object
      properties:
        token:
          type: string
          example: adi_abc123def456
          description: Invitation token (adi_xxx). Use this to look up or cancel the invitation.
        workflowToken:
          type: string
          example: wf_ULA5NSu9pRsUctA9DBmkRQya
          description: Workflow token the invitation will start (wf_xxx).
        channel:
          type: string
          enum:
          - email
          - sms
          example: email
          description: Delivery channel.
        recipient:
          type: string
          example: jane.doe@example.com
          description: Email address or phone number the invitation is sent to.
        reference:
          type: string
          example: cust_42891
          description: Customer-defined identifier echoed back from the create request. Useful for cross-referencing this invitation against your own system.
        locale:
          type: string
          example: en
          description: Language tag the email/SMS was rendered in. Null when no locale was specified at create time.
        status:
          type: string
          enum:
          - pending
          - sent
          - delivered
          - opened
          - started
          - failed
          - completed
          - rejected
          example: pending
          description: 'Lifecycle status of the invitation. Mirrors dossier terminal state once a submission is linked: started=visitor opened the link and a dossier was created; completed=dossier was approved/completed; rejected=dossier was rejected.'
        dossierToken:
          type: string
          example: dossier_4tDH5f7yKN3bRsFy5xTEFrxw
          description: Token of the dossier this invitation produced, once the recipient has started the workflow. Null until then.
        deliveryAttempts:
          type: integer
          format: int32
          example: 1
          description: Number of times this invitation has been successfully sent (initial send + each resend). Capped at 10.
        errorMessage:
          type: string
          description: Failure reason (only populated when status=failed).
        expiresAt:
          type: string
          format: date-time
          example: '2026-05-27T13:54:00Z'
          description: When the invitation link stops working.
        sentAt:
          type: string
          format: date-time
          example: '2026-04-27T13:54:00Z'
          description: When the invitation was dispatched to the channel provider. Null until status flips to sent.
        startedAt:
          type: string
          format: date-time
          example: '2026-04-27T14:10:00Z'
          description: When the recipient first started the workflow (a dossier was created). Null until status flips to started.
        completedAt:
          type: string
          format: date-time
          example: '2026-04-27T14:20:00Z'
          description: When the linked dossier was approved/completed. Null until status flips to completed.
        rejectedAt:
          type: string
          format: date-time
          example: '2026-04-27T14:20:00Z'
          description: When the linked dossier was rejected. Null until status flips to rejected.
        createdAt:
          type: string
          format: date-time
          example: '2026-04-27T13:54:00Z'
          description: When the invitation record was created.
      required:
      - token
      - workflowToken
      - channel
      - recipient
      - reference
      - locale
      - status
      - dossierToken
      - deliveryAttempts
      - errorMessage
      - expiresAt
      - sentAt
      - startedAt
      - completedAt
      - rejectedAt
      - createdAt
      description: Bynn_V1_Entities_AutoDocInvitation model
  securitySchemes:
    PrivateKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`
    PublicKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`