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

# Retrieve an invoice

> Requires the `documents:read` scope.



## OpenAPI

````yaml /openapi.yaml get /invoices/{id}
openapi: 3.1.0
info:
  title: BeanRails Public API
  version: 1.0.0
  description: >
    Read and write BeanRails contacts, works, invoices, quotations and invoice
    payments from your own systems.

    Authenticate every request with an API key. See the guides for scopes,
    pagination and error handling.
servers:
  - url: https://{host}/api/public/v1
    description: Public API v1
    variables:
      host:
        default: app.beanrails.com
        description: The host your BeanRails workspace is served from.
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Customers and leads.
  - name: Contact addresses
    description: Billing, shipping and service addresses of a contact.
  - name: Works
    description: Service or delivery jobs.
  - name: Work PODs
    description: Proof of delivery records submitted by drivers (read only).
  - name: Invoices
    description: Invoices, including status changes.
  - name: Quotations
    description: Quotations, including status changes.
  - name: Invoice payments
    description: Payments recorded against an invoice.
paths:
  /invoices/{id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      tags:
        - Invoices
      summary: Retrieve an invoice
      description: Requires the `documents:read` scope.
      operationId: getInvoice
      responses:
        '200':
          description: The invoice, with items, taxes, discounts and addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The record ID.
      schema:
        type: integer
  schemas:
    DocumentEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Document'
    Document:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        document_type:
          type: string
          enum:
            - invoice
            - quotation
        document_number:
          type: string
        document_date:
          type: string
        document_due_date:
          type:
            - string
            - 'null'
        status:
          type: string
          description: >
            Invoices: `draft`, `unpaid`, `partially_paid`, `paid`, `voided`,
            `refunded`.

            Quotations: `draft`, `pending`, `invoiced`, `completed`,
            `cancelled`.

            Workspaces can rename and add statuses.
        status_name:
          type:
            - string
            - 'null'
        currency:
          type: string
          description: Three letter currency code.
        contact:
          oneOf:
            - $ref: '#/components/schemas/Contact'
            - type: 'null'
        sub_total:
          type: number
        total_discount:
          type: number
        total_tax:
          type: number
        total_amount:
          type: number
        final_amount:
          type: number
          description: The amount due after adjustments.
        amount_paid:
          type: number
        remaining_amount:
          type: number
        pdf_url:
          type:
            - string
            - 'null'
        remarks:
          type:
            - string
            - 'null'
        items:
          type: array
          description: Only on the retrieve endpoints.
          items:
            type: object
            additionalProperties: true
        taxes:
          type: array
          description: Only on the retrieve endpoints.
          items:
            type: object
            additionalProperties: true
        discounts:
          type: array
          description: Only on the retrieve endpoints.
          items:
            type: object
            additionalProperties: true
        addresses:
          type: object
          description: Only on the retrieve endpoints.
          properties:
            billing:
              type:
                - object
                - 'null'
              additionalProperties: true
            shipping:
              type:
                - object
                - 'null'
              additionalProperties: true
        created_at:
          type: string
        updated_at:
          type: string
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: A stable, machine readable code.
              examples:
                - not_found
            message:
              type: string
              description: A human readable explanation.
    Contact:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        contact_number:
          type: string
        company_name:
          type:
            - string
            - 'null'
        first_name:
          type:
            - string
            - 'null'
        last_name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
        lifecycle_stage:
          type: string
          enum:
            - lead
            - customer
        status:
          type:
            - string
            - 'null'
        status_name:
          type:
            - string
            - 'null'
        user:
          type:
            - object
            - 'null'
          description: The assigned user.
          properties:
            id:
              type: integer
            name:
              type: string
            email:
              type: string
        groups:
          type: array
          items:
            type: object
            additionalProperties: true
        primary_address:
          oneOf:
            - $ref: '#/components/schemas/ContactAddress'
            - type: 'null'
        works_count:
          type:
            - integer
            - 'null'
        quotations_count:
          type:
            - integer
            - 'null'
        invoices_count:
          type:
            - integer
            - 'null'
        created_at:
          type: string
        updated_at:
          type: string
    ContactAddress:
      type: object
      additionalProperties: true
      properties:
        id:
          type: integer
        name:
          type: string
        attention:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        company_name:
          type:
            - string
            - 'null'
        mobile_no:
          type:
            - string
            - 'null'
        office_no:
          type:
            - string
            - 'null'
        address1:
          type:
            - string
            - 'null'
        address2:
          type:
            - string
            - 'null'
        city:
          type:
            - string
            - 'null'
        state:
          type:
            - string
            - 'null'
        postcode:
          type:
            - string
            - 'null'
        country:
          type:
            - string
            - 'null'
          description: Two letter country code.
        country_name:
          type:
            - string
            - 'null'
        zone_id:
          type:
            - integer
            - 'null'
        is_primary:
          type: boolean
  responses:
    Unauthorized:
      description: The API key is missing, invalid, revoked or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_api_key
              message: The API key is invalid, revoked, or expired.
    Forbidden:
      description: >-
        The key lacks the required scope, the key owner's role no longer allows
        it, or the owner's account is suspended.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: insufficient_scope
              message: This API key does not have the required scope.
    NotFound:
      description: The record does not exist, or your key is not allowed to see it.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: The requested resource was not found.
    RateLimited:
      description: >-
        You exceeded the key's requests per minute. Wait for the number of
        seconds in the `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds until you can retry.
          schema:
            type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key created in BeanRails, for example `brk_live_...`.

````

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