Valjean Specialty Quotes API

openapi: 3.2.0
info:
  title: Valjean Specialty agent Quotes API
  version: 1.0.0
  summary: Check appetite, send submissions, answer what's needed, follow files, get quotes and ask to bind.
  description: 'For retail agencies'' own software and AI assistants. Every key sees only its own agency''s files. A named Valjean broker works every file: chooses the markets, confirms anything you send, presents quotes and completes binding. Market names appear only on quotes your broker presents.'
  contact:
    name: Valjean Specialty
    email: submissions@valjeanspecialty.com
    url: https://valjeanspecialty.com
  license:
    name: 'Proprietary: for Valjean Specialty agencies'
    url: https://valjeanspecialty.com
  x-mcp:
    url: https://api.valjeanspecialty.com/api/mcp
    transport: streamable-http
    tools:
    - whoami
    - check_appetite
    - get_requirements
    - create_submission
    - list_submissions
    - get_submission
    - answer_questions
    - underwriter_questions
    - add_document
    - get_upload_link
    - finish_upload
    - send_documents
    - whats_new
    - list_documents
    - get_document_link
    - request_bind
    - list_bind_requests
    - withdraw_bind_request
    - ask_instant_quotes
    - list_policies
    - get_policy
    - list_invoices
    - list_quotes
servers:
- url: https://api.valjeanspecialty.com/api/agent/v1
  description: Live and demo (the key decides which book you see)
security:
- bearerAuth: []
- apiKeyHeader: []
- oauth2:
  - read
tags:
- name: Quotes
  description: Quotes your broker has presented.
paths:
  /submissions/{id}/quotes:
    get:
      operationId: listQuotes
      summary: Quotes your broker has presented
      description: 'Only quotes a broker has presented, never ones still being worked. Totals include fees; surplus lines taxes are added at binding.


        Any key (read or read-and-submit).'
      tags:
      - Quotes
      x-valjean-scope: read
      security:
      - bearerAuth: []
      - apiKeyHeader: []
      - oauth2:
        - read
      parameters:
      - name: id
        in: path
        required: true
        description: Submission id.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuoteList'
              example:
                submission_id: 6f2a1c9e-4b3d-4e8a-9c21-7d4e5f6a8b90
                quotes:
                - id: 6f1d2c3b-8a9e-4b7c-9d10-1e2f3a4b5c6d
                  carrier: Magnolia Underwriting Managers
                  lines:
                  - GL
                  - LL
                  premium: 17075
                  fees: 250
                  total: 17325
                  limits: 'GL: $1,000,000 per occurrence / $2,000,000 aggregate'
                  deductibles: 'GL: $2,500 BI/PD'
                  exclusions: null
                  subjectivities: Signed application; currently valued loss runs
                  expires_on: 2026-12-02
                note: 'To bind, reply to your Valjean broker: binding needs a signed request and the subjectivities met.'
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
      x-codeSamples:
      - lang: shell
        label: curl
        source: "curl -X GET \"https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/quotes\" \\\n  -H \"Authorization: Bearer $VALJEAN_KEY\""
      - lang: javascript
        label: Node
        source: "const res = await fetch(\"https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/quotes\", {\n  method: \"GET\",\n  headers: { Authorization: `Bearer ${process.env.VALJEAN_KEY}`, },\n});\nconsole.log(await res.json());"
      - lang: python
        label: Python
        source: "import os, requests\n\nres = requests.get(\n    \"https://api.valjeanspecialty.com/api/agent/v1/submissions/SUBMISSION_ID/quotes\",\n    headers={\"Authorization\": f\"Bearer {os.environ['VALJEAN_KEY']}\"},\n)\nprint(res.json())"
      x-agentic-access:
        action: read
        consequence: Reads only; changes nothing.
        human_in_the_loop: None needed.
        reversible: Nothing to undo.
        confirm_with_user: false
components:
  schemas:
    Quote:
      type: object
      properties:
        id:
          type: string
          format: uuid
        carrier:
          type: string
        lines:
          type: array
          items:
            type: string
          description: Line codes.
        premium:
          type: number
          description: Dollars.
        fees:
          type: number
          description: Policy, inspection, broker and other fees, in dollars.
        total:
          type: number
          description: Premium plus fees, in dollars. Surplus lines taxes are added at binding.
        limits:
          type:
          - string
          - 'null'
        deductibles:
          type:
          - string
          - 'null'
        exclusions:
          type:
          - string
          - 'null'
        subjectivities:
          type:
          - string
          - 'null'
        expires_on:
          type:
          - string
          - 'null'
          format: date
      required:
      - id
      - carrier
      - lines
      - premium
      - fees
      - total
      - limits
      - deductibles
      - exclusions
      - subjectivities
      - expires_on
    QuoteList:
      type: object
      properties:
        submission_id:
          type: string
          format: uuid
        quotes:
          type: array
          items:
            $ref: '#/components/schemas/Quote'
        note:
          type: string
      required:
      - submission_id
      - quotes
      - note
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable code, e.g. invalid_request, read_only, not_found, closed, rate_limited.
            message:
              type: string
              description: Plain-English explanation you can show a person.
            issues:
              type: array
              items:
                type: string
              description: 'Validation problems, as "field: problem" (400 invalid_request only).'
          required:
          - code
          - message
      required:
      - error
  responses:
    Forbidden:
      description: 'Not allowed: read_only (a read key tried to submit), agency_not_active (no signed broker agreement), not_offered (instant quotes are off), forbidden (API access off for the agency). Don''t retry.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: read_only
              message: This key can read only. Ask your Valjean broker for a key that can submit.
    NotFound:
      description: Not found, or not your agency's (not_found). The API never says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Submission not found.
    Unauthorized:
      description: 'Key or token missing, wrong, expired or revoked (unauthorized). Don''t retry: get a new key or sign in again.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: This API key isn't valid. Ask your Valjean broker for a new one.
    ServerError:
      description: Something went wrong on Valjean's side (server_error). Safe to retry later; creates are idempotent with client_reference or an Idempotency-Key header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: server_error
              message: Something went wrong. Try again shortly.
    RateLimited:
      description: 'Too many requests (rate_limited): 120 a minute per key, 30 a minute per IP on public endpoints, counted across all of Valjean''s servers. Wait Retry-After seconds.'
      headers:
        Retry-After:
          description: Seconds to wait.
          schema:
            type: integer
            example: 60
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests. Try again in a minute.
  headers:
    RateLimitPolicy:
      description: 'The rate limit for this key, as an IETF RateLimit-Policy: 120 requests (q) per 60-second window (w), counted across all of Valjean''s servers. Over it, you get 429 with Retry-After.'
      schema:
        type: string
        example: '"per-key";q=120;w=60'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: vjk_live_… / vjk_demo_… API key, or an OAuth access token (vjat_…)
      description: 'Send the key as `Authorization: Bearer vjk_…`. Keys come from your agency portal or your Valjean broker.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: The same API key in an X-Api-Key header, for tools that can't set Authorization.
    oauth2:
      type: oauth2
      description: 'For AI apps that connect by signing in. Authorization code flow with PKCE (S256 only), public clients (no secret), dynamic client registration at https://api.valjeanspecialty.com/oauth/register. Discovery: https://api.valjeanspecialty.com/.well-known/oauth-authorization-server. Access tokens last 1 hour; refresh tokens 30 days and rotate on use. Tokens stop when the API key or portal link that approved them is revoked.'
      flows:
        authorizationCode:
          authorizationUrl: https://api.valjeanspecialty.com/oauth/authorize
          tokenUrl: https://api.valjeanspecialty.com/oauth/token
          refreshUrl: https://api.valjeanspecialty.com/oauth/token
          scopes:
            read: Appetite, requirements, status, quotes, documents, policies
            submit: Also send files, answers, documents, bind requests and instant-quote asks
x-event-types:
- submission.received
- submission.status_changed
- needs.requested
- markets.updated
- quote.presented
- bind.status_changed
- policy.bound
- policy.status_changed
- document.available
- invoice.sent
- invoice.paid
- invoice.overdue