Street.co.uk Invoices API

openapi: 3.2.0
info:
  title: Street Open Invoices API
  description: Build on top of the UKs most advanced Estate Agency software.
  version: '1.0'
  contact:
    name: Street API Development Team
    url: https://street.co.uk
    email: apis@street.co.uk
servers:
- url: https://street.co.uk/open-api/v1
  description: Production.
- url: https://demo.street.co.uk/open-api/v1
  description: Testing.
security:
- your-api-token: []
tags:
- name: Invoices
  description: Invoices endpoints for this API.
paths:
  /invoices:
    get:
      summary: Get all Invoices
      tags:
      - Invoices
      operationId: get-invoices
      description: This endpoint retrieves multiple paginated invoices along with `meta` and `pagination` information.
      parameters:
      - schema:
          type: array
          items:
            type: string
            uniqueItems: true
            minItems: 1
            enum:
            - property
            - owner
            - line_items
        in: query
        name: include
        description: Optional related entities to include in the results.
        style: form
        explode: false
      - schema:
          type: boolean
        in: query
        name: filter[paid]
        description: Filter whether the invoice is paid or not
      - schema:
          type: boolean
        in: query
        name: filter[voided]
        description: Filter whether the invoice is voided or not
      - schema:
          type: array
          items:
            type: string
            uniqueItems: true
            enum:
            - sales
            - lettings
        in: query
        name: filter[invoice_type]
        description: Optional filter to filter between sales and lettings invoices.
        style: form
        explode: false
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/page_number'
      responses:
        '200':
          description: Get all Invoices.
          headers: {}
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
                  included:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/IncludedProperty'
                      - $ref: '#/components/schemas/IncludedOwner'
                      - $ref: '#/components/schemas/IncludedFees'
                  links:
                    $ref: '#/components/schemas/IncludedLinks'
                  meta:
                    allOf:
                    - $ref: '#/components/schemas/Pagination'
                  jsonapi:
                    $ref: '#/components/schemas/JsonApi'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
  /invoices/{invoice_id}:
    parameters:
    - schema:
        type: string
      name: invoice_id
      in: path
      required: true
    get:
      summary: Get a single Invoice.
      tags:
      - Invoices
      responses:
        '200':
          description: Get Invoice by `UUID`.
          headers: {}
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
                  included:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/IncludedProperty'
                      - $ref: '#/components/schemas/IncludedOwner'
                      - $ref: '#/components/schemas/IncludedFees'
                  links:
                    $ref: '#/components/schemas/IncludedLinks'
                  meta:
                    type: object
                  jsonapi:
                    $ref: '#/components/schemas/JsonApi'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '415':
          $ref: '#/components/responses/415'
        '500':
          $ref: '#/components/responses/500'
      operationId: get-invoices-invoice_id
      description: This endpoint retrieves a single Invoice by its `UUID`.
      parameters:
      - schema:
          type: array
          items:
            type: string
            uniqueItems: true
            minItems: 1
            enum:
            - property
            - owner
            - line_items
        in: query
        name: include
        description: Optional related entities to include in the results.
        style: form
        explode: false
    patch:
      summary: Mark an Invoice as paid
      operationId: patch-invoices-invoiceId
      tags:
      - Invoices
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Invoice'
                  links:
                    $ref: '#/components/schemas/IncludedLinks'
                  meta:
                    type: object
                  jsonapi:
                    $ref: '#/components/schemas/JsonApi'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '409':
          $ref: '#/components/responses/409'
        '415':
          $ref: '#/components/responses/415'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
      description: This endpoint allows you to mark an Invoice as paid by providing a `paid_at` date.
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                      - invoice
                    id:
                      type: string
                      format: uuid
                    attributes:
                      type: object
                      required:
                      - paid_at
                      properties:
                        paid_at:
                          type: string
                          format: date-time
                          description: The date the invoice was paid.
                          example: '2026-02-24T14:30:00Z'
              required:
              - data
        description: Mark the invoice as paid by providing the paid date.
components:
  responses:
    '406':
      description: The HTTP 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '400':
      description: The HTTP 400 Bad Request response status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
    '404':
      description: The HTTP 404 Not Found response status code indicates that the server cannot find the requested resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '403':
      description: The HTTP 403 Forbidden response status code indicates that the server understands the request but refuses to authorize it.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '409':
      description: The HTTP 409 Conflict response status code indicates a request conflict with the current state of the target resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '500':
      description: The HTTP 500 Internal Server Error server error response code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
    '415':
      description: The HTTP 415 Unsupported Media Type client error response code indicates that the server refuses to accept the request because the payload format is in an unsupported format.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
    '422':
      description: The 422 Unprocessable Content response status code indicates that the server understands the content type of the request entity, and the syntax of the request entity is correct, but it was unable to process the contained instructions.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiMultiErrorResponseBody'
    '401':
      description: The HTTP 401 Unauthorized response status code indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource.
      content:
        application/vnd.api+json:
          schema:
            $ref: '#/components/schemas/jsonApiErrorResponseBody'
  schemas:
    IncludedResource:
      title: Included Resource
      type: object
      examples: []
      required:
      - type
      - id
      properties:
        type:
          type: string
        id:
          type: string
          format: uuid
        attributes:
          type: object
        relationships:
          type:
          - object
          - 'null'
        meta:
          $ref: '#/components/schemas/Meta'
    IncludedProperty:
      title: Property (included)
      allOf:
      - $ref: '#/components/schemas/IncludedResource'
      - type: object
        properties:
          type:
            type: string
            enum:
            - property
          attributes:
            $ref: '#/components/schemas/PropertyAttributes'
          relationships:
            type: object
            properties:
              branch:
                allOf:
                - $ref: '#/components/schemas/RelationshipSingular'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - branch
    jsonApiErrorResponseBody:
      title: JSON:API Error Response Body
      description: Response body for JSON:API errors, containing an array of `errors` in place of the `data` property provided in JSON:API success responses. Used for non-400/500 error codes where only a single error is expected.
      type: object
      properties:
        meta:
          type: object
        source:
          type: object
          description: The primary source of the conflict for 409 responses.
          properties:
            pointer:
              type: string
              description: JSON Pointer to the conflicting request value.
            parameter:
              type: string
              description: URI parameter related to the conflict.
        errors:
          description: An array of error objects providing additional information about problems encountered while processing the request.
          type: array
          maxItems: 1
          items:
            $ref: '#/components/schemas/jsonApiError'
      required:
      - errors
    RelationshipSingular:
      title: Relationship Singular
      description: Inheritable schema for 1:1 relationships. Data may be null if the relationship is empty.
      type: object
      properties:
        data:
          oneOf:
          - type: object
            properties:
              type:
                type: string
              id:
                type: string
                format: uuid
                example: a827a3ae-4c74-4c32-8b42-42248d4010d3
            required:
            - type
            - id
          - type: 'null'
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            related:
              $ref: '#/components/schemas/Link'
    Pagination:
      title: Pagination
      description: Pagination object - JSON:API Standard.
      type: object
      properties:
        pagination:
          type: object
          properties:
            total:
              type: integer
              example: 226
            count:
              type: integer
              example: 10
            per_page:
              type: integer
              example: 10
            current_page:
              type: integer
              example: 1
            total_pages:
              type: integer
              example: 23
      x-examples:
        example-1:
          pagination:
            total: 226
            count: 10
            per_page: 10
            current_page: 1
            total_pages: 23
      examples:
      - pagination:
          total: 226
          count: 10
          per_page: 10
          current_page: 1
          total_pages: 23
    Link:
      title: Link
      oneOf:
      - description: a string containing the link's URL
        type: string
        format: uri-reference
      - type: object
        required:
        - href
        properties:
          href:
            description: a string containing the link's URL
            type: string
            format: uri-reference
          meta:
            $ref: '#/components/schemas/Meta'
    PropertyAttributes:
      type: object
      title: Property (attributes)
      properties:
        is_sales:
          type: boolean
        is_lettings:
          type: boolean
        company_owned:
          type: boolean
        is_commercial:
          type: boolean
        is_residential:
          type: boolean
        address:
          $ref: '#/components/schemas/AddressSimple'
        inline_address:
          type: string
        public_address:
          type: string
        status:
          type: string
          enum:
          - Not On The Market
          - Valuation Lost
          - Valuation Booked
          - Provisional Valuation Booked
          - Valuation Pending
          - Valuation Cancelled
          - Valuation Completed
          - Instructed
          - For Sale
          - Under Offer
          - Sold STC
          - Exchanged
          - Let
          - To Let
          - Let Agreed
          - For Sale and To Let
          - Withdrawn Sales
          - Withdrawn Lettings
          - Withdrawn Sales And Lettings
          - Completed
        bedrooms:
          type: integer
        bathrooms:
          type: integer
        receptions:
          type: integer
        floor_area:
          type:
          - string
          - 'null'
        plot_area:
          type:
          - string
          - 'null'
        land_area:
          type:
          - string
          - 'null'
        full_description:
          type:
          - string
          - 'null'
        short_description:
          type:
          - string
          - 'null'
        location_summary:
          type:
          - string
          - 'null'
        full_description_lettings:
          type:
          - string
          - 'null'
        short_description_lettings:
          type:
          - string
          - 'null'
        location_summary_lettings:
          type:
          - string
          - 'null'
        property_type:
          type: string
        property_style:
          type: string
        property_age_bracket:
          type: string
        construction_year:
          type:
          - string
          - integer
          - 'null'
        is_listed_building:
          type:
          - boolean
          - 'null'
        is_conservation_area:
          type:
          - boolean
          - 'null'
        tenure:
          type: string
        tenure_notes:
          type:
          - string
          - 'null'
        lease_expiry_year:
          type:
          - string
          - 'null'
        lease_expiry_date:
          type:
          - string
          - 'null'
          format: date
        display_property_style:
          type: string
        work_required:
          type: boolean
        heating_system:
          type: string
        council_tax_band:
          type: string
        council_tax_cost:
          type:
          - integer
          - 'null'
        local_authority:
          type:
          - string
          - 'null'
        service_charge:
          type: integer
        service_charge_period:
          type: string
          default: month
        service_charge_notes:
          type:
          - string
          - 'null'
        ground_rent:
          type:
          - integer
          - 'null'
        ground_rent_period:
          type: string
          default: month
        ground_rent_review_period_years:
          type:
          - integer
          - 'null'
        ground_rent_uplift:
          type:
          - integer
          - 'null'
        ground_rent_expiry:
          type:
          - string
          - 'null'
        has_outdoor_space:
          type:
          - boolean
          - 'null'
        shared_ownership:
          type: boolean
          default: false
        shared_ownership_notes:
          type:
          - string
          - 'null'
        shared_ownership_rent:
          type:
          - integer
          - 'null'
        shared_ownership_rent_frequency:
          type:
          - string
          - 'null'
        shared_ownership_percentage_sold:
          type:
          - integer
          - 'null'
        tags:
          type: array
          uniqueItems: true
          items:
            type: object
            properties:
              name:
                type: string
              slug:
                type: string
              order:
                type: number
        features:
          type: array
          uniqueItems: true
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
                description: The ID of the feature
              name:
                type: string
              order:
                type: number
              include_on_portals:
                type: boolean
              highlight:
                type: boolean
        material_information:
          type: object
          properties:
            council_tax_band:
              type:
              - string
              - 'null'
              example: D
              maxLength: 1
            lease_expiry_date:
              type:
              - string
              - 'null'
              format: date
            ground_rent_pence:
              type:
              - integer
              - 'null'
            ground_rent_period:
              type:
              - string
              - 'null'
            ground_rent_expiry:
              type:
              - string
              - 'null'
              format: date
            ground_rent_review_period_years:
              type:
              - integer
              - 'null'
            ground_rent_uplift:
              type:
              - integer
              - 'null'
              description: Value is a percentage
            service_charge_pence:
              type:
              - integer
              - 'null'
            service_charge_period:
              type:
              - string
              - 'null'
            service_charge_notes:
              type:
              - string
              - 'null'
            water_supply:
              type:
              - array
              - 'null'
              uniqueItems: true
              minItems: 1
              items:
                type: string
                enum:
                - direct_main_waters
                - wells
                - boreholes
                - springs
                - other
            water_supply_other:
              type:
              - string
              - 'null'
            electricity_supply:
              type:
              - array
              - 'null'
              uniqueItems: true
              minItems: 1
              items:
                type: string
                enum:
                - national_grid
                - wind_turbine
                - solar_panels
                - generator
                - other
            electricity_supply_other:
              type:
              - string
              - 'null'
            sewerage:
              type:
              - array
              - 'null'
              uniqueItems: true
              minItems: 1
              items:
                type: string
                enum:
                - standard
                - septic_tank
                - sewage_treatment_plants
                - cesspit
                - cesspool
                - other
            sewerage_other:
              type:
              - string
              - 'null'
            heating_supply:
              type:
              - array
              - 'null'
              uniqueItems: true
              minItems: 1
              items:
                type: string
                enum:
                - electric_central
                - gas_central
                - gas_other
                - communal_heating
                - lpg_central
                - wood_burner
                - biomass_boiler
                - solar_panels
                - heat_pump
                - other
            heating_supply_other:
              type:
              - string
              - 'null'
            heating_system:
              type:
              - string
              - 'null'
            broadband:
              type:
              - string
              - 'null'
              enum:
              - adsl
              - cable
              - fttc
              - fttp
              - null
            has_restrictions:
              type:
              - boolean
              - 'null'
            has_required_access:
              type:
              - boolean
              - 'null'
            public_right_of_way:
              type:
              - boolean
              - 'null'
            flood_risk:
              type:
              - boolean
              - 'null'
            sources_of_flooding:
              type:
              - array
              - 'null'
              items:
                type: string
            sources_of_flooding_other:
              type:
              - string
              - 'null'
            has_flood_defences:
              type:
              - boolean
              - 'null'
            has_flooded_in_last_five_years:
              type:
              - boolean
              - 'null'
            adaptations_list:
              type:
              - array
              - 'null'
              items: {}
            adaptations_other:
              type:
              - string
              - 'null'
        viewing_booking_url:
          type:
          - string
          - 'null'
        last_instructed_sales_at:
          type:
          - string
          - 'null'
          format: date-time
        last_instructed_lettings_at:
          type:
          - string
          - 'null'
          format: date-time
        last_exchanged_at:
          type:
          - string
          - 'null'
          format: date-time
        last_completed_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        custom_meta_data:
          type:
          - object
          - array
          items: {}
        lead_source:
          type:
          - string
          - 'null'
        publish_after:
          type:
          - string
          - 'null'
          format: date-time
        archived_at:
          type:
          - string
          - 'null'
          format: date-time
        virtual_tour:
          type:
          - string
          - 'null'
          format: uri
        property_urls:
          type:
          - array
          - 'null'
          items:
            type: object
            properties:
              title:
                type: string
              type:
                type: string
                enum:
                - image
                - floor_plan
                - brochure
                - virtual_tour
                - audio_tour
                - ipack
              url:
                type: string
                format: uri
                maxLength: 2048
            required:
            - title
            - type
            - url
    AddressSimple:
      title: Address (simple)
      type: object
      properties:
        single_line:
          type: string
          example: 19 Lansdowne Road, Monton, Manchester
        anon_single_line:
          type: string
          example: Lansdowne Road, Monton, Manchester
        building_number:
          type:
          - string
          - 'null'
          example: '19'
        building_name:
          type:
          - string
          - 'null'
        street:
          type:
          - string
          - 'null'
        line_1:
          type: string
          example: 19 Lansdowne Road
        line_2:
          type:
          - string
          - 'null'
          example: Monton
        line_3:
          type:
          - string
          - 'null'
          example: Manchester
        line_4:
          type:
          - string
          - 'null'
        town:
          type:
          - string
          - 'null'
          example: Manchester
        country:
          type: string
          example: United Kingdom
        postcode:
          type: string
          example: M30 9PA
        udprn:
          type:
          - string
          - 'null'
          example: '28327204'
        geo:
          type: object
          properties:
            lat:
              type:
              - number
              - 'null'
              example: 0.2365698
              format: float
            lng:
              type:
              - number
              - 'null'
              example: 53.023654
              format: float
        royal_mail:
          type:
          - object
          - 'null'
          properties:
            postcode:
              type: string
            post_town:
              type: string
            thoroughfare:
              type: string
            building_name:
              type:
              - string
              - 'null'
            building_number:
              type:
              - string
              - 'null'
            department_name:
              type:
              - string
              - 'null'
            organisation_name:
              type:
              - string
              - 'null'
            sub_building_name:
              type:
              - string
              - 'null'
            dependent_locality:
              type:
              - string
              - 'null'
            dependent_thoroughfare:
              type:
              - string
              - 'null'
            double_dependent_locality:
              type:
              - string
              - 'null'
        street_group_property_id:
          type:
          - string
          - 'null'
    InvoiceAttributes:
      title: Invoice (attributes)
      type: object
      properties:
        invoice_prefix:
          type: string
        invoice_number:
          type: integer
        total_amount:
          type: integer
          example: 425000
        total_amount_vat:
          type: integer
          example: 42500
        paid:
          type: boolean
        paid_at:
          type:
          - string
          - 'null'
          format: date-time
        due_date:
          type: string
          format: date-time
        voided_at:
          type:
          - string
          - 'null'
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    IncludedFees:
      title: Fees (included)
      allOf:
      - $ref: '#/components/schemas/IncludedResource'
      - type: object
        properties:
          type:
            type: string
            enum:
            - fee
          attributes:
            $ref: '#/components/schemas/FeeAttributes'
    RelationshipPlural:
      title: Relationship Plural
      description: This is a inheritable schema to allow you to easily add relationships to your main schemas. This should be used for `1:n` relationships.
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              id:
                type: string
                example: a827a3ae-4c74-4c32-8b42-42248d4010d3
        links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/Link'
            related:
              $ref: '#/components/schemas/Link'
    Meta:
      title: Meta Information
      description: The server's implementation.
      type: object
    jsonApiError:
      title: JSON:API Error Object
      description: A JSON:API object representing a single error.
      type: object
      properties:
        title:
          type: string
        detail:
          type: string
        code:
          type: string
        source:
          type: object
          description: An object containing references to the primary source of the error.
          properties:
            pointer:
              type: string
              description: A JSON Pointer to the value in the request document that caused the error.
            parameter:
              type: string
              description: A string indicating which URI query parameter caused the error.
      required:
      - title
      examples:
      - title: 401 Unauthorized
        detail: The requester is not authorized to access the resource.
        code: '401'
    Invoice:
      title: Invoice
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - type: object
        properties:
          type:
            type: string
            enum:
            - invoice
          attributes:
            $ref: '#/components/schemas/InvoiceAttributes'
          relationships:
            type: object
            properties:
              property:
                allOf:
                - $ref: '#/components/schemas/RelationshipSingular'
                - type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - property
              owner:
                allOf:
                - $ref: '#/components/schemas/RelationshipSingular'
                - type: object
                  properties:
        

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/street-co/refs/heads/main/openapi/street-co-invoices-api-openapi.yml