Street.co.uk People API

openapi: 3.2.0
info:
  title: Street Open People 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: People
  description: People endpoints for this API.
paths:
  /people:
    get:
      summary: Get all People
      tags:
      - People
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Person'
                  included:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/IncludedProperty'
                      - $ref: '#/components/schemas/IncludedApplicant'
                  links:
                    $ref: '#/components/schemas/Links'
                  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'
      operationId: get-people
      parameters:
      - $ref: '#/components/parameters/filter_address'
      - $ref: '#/components/parameters/filter_email_address'
      - $ref: '#/components/parameters/filter_telephone_number'
      - $ref: '#/components/parameters/filter_trashed'
      - $ref: '#/components/parameters/filter_created_from'
      - $ref: '#/components/parameters/filter_created_to'
      - $ref: '#/components/parameters/filter_updated_from'
      - $ref: '#/components/parameters/filter_updated_to'
      - schema:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            type: string
            enum:
            - ownedProperties
            - applicants
        in: query
        name: include
        description: Optional related entities to include in the results.
        explode: false
        style: form
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/page_number'
      description: This endpoint retrieves multiple paginated people along with `meta` and `pagination` information.
  /people/{person_id}:
    parameters:
    - schema:
        type: string
        format: uuid
      name: person_id
      in: path
      required: true
      description: The UUID of the Person.
    get:
      summary: Get a single Person
      tags:
      - People
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Person'
                  included:
                    type: array
                    items:
                      anyOf:
                      - $ref: '#/components/schemas/IncludedProperty'
                      - $ref: '#/components/schemas/IncludedApplicant'
                  links:
                    $ref: '#/components/schemas/IncludedLinks'
                  meta:
                    type: object
                  jsonapi:
                    $ref: '#/components/schemas/JsonApi'
              examples:
                Person with included property:
                  value:
                    data:
                      id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                      type: person
                      attributes:
                        full_name: string
                        title: Mrs
                        first_name: Jane
                        last_name: Doe
                        address:
                          single_line: 19 Lansdowne Road, Monton, Manchester
                          anon_single_line: Lansdowne Road, Monton, Manchester
                          building_number: '19'
                          building_name: string
                          street: Lansdowne Road
                          line_1: 19 Lansdowne Road
                          line_2: Monton
                          line_3: Manchester
                          line_4: string
                          country: United Kingdom
                          postcode: M30 9PA
                          udprn: '28327204'
                          geo:
                            lat: 0.2365698
                            lng: 53.023654
                          royal_mail:
                            postcode: string
                            post_town: string
                            thoroughfare: string
                            building_name: string
                            building_number: string
                            department_name: string
                            organisation_name: string
                            sub_building_name: string
                            dependent_locality: string
                            dependent_thoroughfare: string
                            double_dependent_locality: string
                          street_group_property_id: string
                        telephone_numbers:
                        - value: '+441632960911'
                          notes: string
                          primary: true
                        email_addresses:
                        - value: john@johndoe.com
                          notes: string
                          primary: true
                        marketing_consent: true
                        contact_preferences:
                          email: true
                          post: true
                          text: true
                          phone: true
                        statuses:
                          vendor: null
                          landlord: null
                          tenant: null
                        created_at: '2019-08-24T14:15:22Z'
                        updated_at: '2019-08-24T14:15:22Z'
                      relationships:
                        properties:
                          data:
                          - type: property
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                          links:
                            self: ../dictionary
                            related: ../dictionary
                        applicants:
                          data:
                          - type: applicant
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                          links:
                            self: ../dictionary
                            related: ../dictionary
                        notes:
                          data:
                          - type: note
                            id: a827a3ae-4c74-4c32-8b42-42248d4010d3
                          links:
                            self: ../dictionary
                            related: ../dictionary
                    included:
                    - type: property
                      id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
                      attributes:
                        sales: true
                        lettings: true
                        is_sales: true
                        is_lettings: true
                        company_owned: true
                        address:
                          single_line: 19 Lansdowne Road, Monton, Manchester
                          anon_single_line: Lansdowne Road, Monton, Manchester
                          building_number: '19'
                          building_name: string
                          street: Lansdowne Road
                          line_1: 19 Lansdowne Road
                          line_2: Monton
                          line_3: Manchester
                          line_4: string
                          country: United Kingdom
                          postcode: M30 9PA
                          udprn: '28327204'
                          geo:
                            lat: 0.2365698
                            lng: 53.023654
                          royal_mail:
                            postcode: string
                            post_town: string
                            thoroughfare: string
                            building_name: string
                            building_number: string
                            department_name: string
                            organisation_name: string
                            sub_building_name: string
                            dependent_locality: string
                            dependent_thoroughfare: string
                            double_dependent_locality: string
                          street_group_property_id: string
                        status: Not On The Market
                        owner:
                        - full_name: string
                          title: Mrs
                          first_name: Jane
                          last_name: Doe
                          address:
                            single_line: 19 Lansdowne Road, Monton, Manchester
                            anon_single_line: Lansdowne Road, Monton, Manchester
                            building_number: '19'
                            building_name: string
                            street: Lansdowne Road
                            line_1: 19 Lansdowne Road
                            line_2: Monton
                            line_3: Manchester
                            line_4: string
                            country: United Kingdom
                            postcode: M30 9PA
                            udprn: '28327204'
                            geo:
                              lat: 0.2365698
                              lng: 53.023654
                            royal_mail:
                              postcode: string
                              post_town: string
                              thoroughfare: string
                              building_name: string
                              building_number: string
                              department_name: string
                              organisation_name: string
                              sub_building_name: string
                              dependent_locality: string
                              dependent_thoroughfare: string
                              double_dependent_locality: string
                            street_group_property_id: string
                          telephone_numbers:
                          - value: '+441632960911'
                            notes: string
                            primary: true
                          email_addresses:
                          - value: john@johndoe.com
                            notes: string
                            primary: true
                          marketing_consent: true
                          contact_preferences:
                            email: true
                            post: true
                            text: true
                            phone: true
                        bedrooms: 0
                        bathrooms: 0
                        receptions: 0
                        floor_area: string
                        plot_area: string
                        land_area: string
                        property_type: string
                        property_style: string
                        property_age_bracket: string
                        construction_year: string
                        tenure: string
                        tenure_notes: string
                        lease_expiry_year: string
                        lease_expiry_date: '2019-08-24'
                        display_property_style: string
                        work_required: true
                        heating_system: string
                        council_tax_band: string
                        council_tax_cost: 0
                        local_authority: string
                        service_charge: 0
                        service_charge_period: month
                        service_charge_notes: string
                        ground_rent: 0
                        ground_rent_period: month
                        ground_rent_review_period_years: 0
                        ground_rent_uplift: 0
                        ground_rent_expiry: string
                        has_outdoor_space: true
                        shared_ownership: false
                        shared_ownership_notes: string
                        shared_ownership_rent: 0
                        shared_ownership_rent_frequency: string
                        shared_ownership_percentage_sold: 0
                        listings:
                        - price_qualifier: None
                          archived: true
                          is_low_profile: true
                          is_not_in_property_feed_api: true
                          is_auction: false
                          new_home: true
                          retirement: true
                          full_description: string
                          short_description: string
                          location_summary: string
                          has_parking: true
                          virtual_tour: ../dictionary
                          type: sales
                          price: 500000
                          status: For Sale
                        tags:
                        - name: Example tag
                          slug: example-tag
                          order: 0
                        features:
                        - id: 7f064215-0b9c-45e5-bd91-02913c050a9a
                          name: Example feature
                          order: 0
                          include_on_portals: false
                          highlight: true
                        viewing_booking_url: string
                        last_instructed_sales_at: '2019-08-24T14:15:22Z'
                        last_instructed_lettings_at: '2019-08-24T14:15:22Z'
                        last_exchanged_at: '2019-08-24T14:15:22Z'
                        last_completed_at: '2019-08-24T14:15:22Z'
                        created_at: '2019-08-24T14:15:22Z'
                        updated_at: '2019-08-24T14:15:22Z'
                      relationships: {}
                      links:
                        self: ../dictionary
                        related: ../dictionary
                    links:
                      self: ../dictionary
                      related: ../dictionary
                    meta: {}
                    jsonapi:
                      version: string
                      meta: {}
        '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-people-personId
      description: This endpoint retrieves a single company by its `UUID`.
      parameters:
      - schema:
          type: array
          uniqueItems: true
          minItems: 1
          items:
            type: string
            enum:
            - ownedProperties
            - applicants
        in: query
        name: include
        description: Optional related entities to include in the results.
        explode: false
        style: form
    patch:
      summary: Update a Person
      operationId: patch-people-personId
      responses:
        '200':
          description: OK.
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/BaseModel'
                    - type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        type:
                          type: string
                          enum:
                          - person
                        attributes:
                          $ref: '#/components/schemas/PersonAttributes'
        '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 update specific fields with a `Person` record via their `UUID` by providing amended core information such as name, address and contact details or marketing and contact preference changes.
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      type: string
                    id:
                      type: string
                      format: uuid
                    attributes:
                      $ref: '#/components/schemas/PersonRequestBody'
        description: ''
      tags:
      - People
components:
  parameters:
    page_size:
      name: page[size]
      description: Set the number of results per page.
      in: query
      required: false
      schema:
        type: number
        minimum: 1
        maximum: 250
        example: 25
    filter_address:
      name: filter[address]
      in: query
      required: false
      schema:
        type: string
      description: Filter results by their address, this is a fuzzy wildcard match on the full address string.
    filter_created_from:
      name: filter[created_from]
      in: query
      required: false
      schema:
        type: string
        format: date-time
      description: Filter by results created after the provided date.
    filter_email_address:
      name: filter[email_address]
      in: query
      required: false
      schema:
        type: string
        format: email
        example: alice.walker@example.com
      description: Filter results by an associated email address
    filter_updated_from:
      name: filter[updated_from]
      in: query
      required: false
      schema:
        type: string
        format: date-time
      description: Filter by results updated after the provided date.
    filter_updated_to:
      name: filter[updated_to]
      in: query
      required: false
      schema:
        type: string
        format: date-time
      description: Filter by results updated before the provided date.
    filter_telephone_number:
      name: filter[telephone_number]
      in: query
      required: false
      schema:
        type: string
      description: Filter results by an associated telephone number. The number must be in full international dialing format e.g. +441614960137
    filter_created_to:
      name: filter[created_to]
      in: query
      required: false
      schema:
        type: string
        format: date-time
      description: Filter by results created before the provided date.
    filter_trashed:
      name: filter[trashed]
      in: query
      required: false
      schema:
        type: string
        enum:
        - with
        - only
      description: Optionally return result WITH deleted results or return ONLY deleted results.
    page_number:
      name: page[number]
      description: Set the page number.
      in: query
      required: false
      schema:
        type: number
        minimum: 1
        example: 3
  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'
    '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'
    '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'
    '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'
    '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'
  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'
    EmailAddressSimple:
      title: Email Address (simple)
      description: An email address, can be related to a person and/or a company.
      type: object
      properties:
        value:
          type: string
          example: john@johndoe.com
          format: email
        notes:
          type:
          - string
          - 'null'
        primary:
          type: boolean
    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
    PersonRequestBody:
      title: Person (request)
      type: object
      properties:
        title:
          type:
          - string
          - 'null'
        first_name:
          type: string
        last_name:
          type: string
        marketing_consent:
          type: boolean
        contact_preferences:
          type: object
          properties:
            email:
              type: boolean
            text:
              type: boolean
            post:
              type: boolean
            phone:
              type: boolean
      required:
      - first_name
      - last_name
    Person:
      allOf:
      - $ref: '#/components/schemas/BaseModel'
      - properties:
          type:
            type: string
            enum:
            - person
          attributes:
            $ref: '#/components/schemas/PersonAttributes'
          relationships:
            type: object
            properties:
              properties:
                description: All Properties owned by this Person
                allOf:
                - $ref: '#/components/schemas/RelationshipPlural'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          type:
                            type: string
                            enum:
                            - property
              applicants:
                description: All sales and letting Applicants this person is a part of.
                allOf:
                - $ref: '#/components/schemas/RelationshipPlural'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          type:
                            type: string
                            enum:
                            - applicant
              notes:
                description: Any Notes attached to this Person.
                allOf:
                - $ref: '#/components/schemas/RelationshipPlural'
                - type: object
                  properties:
                    data:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            format: uuid
                          type:
                            type: string
                            enum:
                            - note
      title: Person
      type: object
    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
    TelephoneNumberSimple:
      title: Telephone Number (simple)
      description: An telephone number, can be related to a person and/or a company.
      type: object
      properties:
        value:
          type: string
          example: '+441632960911'
        notes:
          type:
          - string
          - 'null'
        primary:
          type: boolean
    PersonAttributes:
      title: Person (attributes)
      type: object
      properties:
        full_name:
          type: string
        title:
          type:
          - string
          - 'null'
          example: Mrs
        first_name:
          type: string
          example: Jane
        last_name:
          type: string
          example: Doe
        address:
          oneOf:
          - $ref: '#/components/schemas/AddressSimple'
          - type: 'null'
        telephone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/TelephoneNumberSimple'
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/EmailAddressSimple'
        marketing_consent:
          type:
          - boolean
          - 'null'
        contact_preferences:
          type: object
          properties:
            email:
              type: boolean
            post:
              type: boolean
            text:
              type: boolean
            phone:
              type: boolean
        statuses:
          type: object
          minProp

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