evictionsapi-com Landlords API

openapi: 3.2.0
info:
  title: Evictionsapi Com Landlords API
  version: 0.0.0
  contact:
    email: hello@evictionsapi.com
  description: 'Operations tagged Landlords across 3 of this provider''s published API definitions: api.evictionsapi.com.json, evictionsapi-com-api-evictions-openapi.json, evictionsapi-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.evictionsapi.com
tags:
- name: Landlords
paths:
  /v1/landlords:
    get:
      summary: The owners the organization acts for, by name, each with how many of its cases…
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: includeArchived
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      responses:
        '200':
          description: The landlords.
          content:
            application/json:
              schema:
                type: object
                required:
                - items
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Landlord'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: getV1Landlords
      x-operation-id-source: derived
    post:
      summary: Save an owner the organization acts for. `ownerOfRecord` defaults to the name.
      security:
      - ApiKey: []
      - SessionToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                isEntity:
                  type: boolean
                plaintiffType:
                  anyOf:
                  - type: string
                    enum:
                    - individual
                    - corporation
                    - llc
                    - partnership
                    - trust
                    - estate
                    - other
                  - type: 'null'
                ownerOfRecord:
                  type: string
                  minLength: 1
                  maxLength: 200
                contact:
                  type: object
                  properties:
                    address:
                      type: string
                      minLength: 1
                      maxLength: 500
                    phone:
                      type: string
                      minLength: 1
                      maxLength: 40
                    email:
                      type: string
                      maxLength: 254
                      format: email
                      pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                  - address
                  - phone
                  additionalProperties: false
                notes:
                  type: string
                  maxLength: 1000
              required:
              - name
              - isEntity
              - contact
              additionalProperties: false
      responses:
        '201':
          description: The landlord.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Landlord'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: postV1Landlords
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
  /v1/landlords/{id}:
    get:
      summary: One landlord, archived or not, with its current management agreement.
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The landlord, and its management agreement or null.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Landlord'
                - type: object
                  required:
                  - agreement
                  properties:
                    agreement:
                      oneOf:
                      - $ref: '#/components/schemas/LandlordDocument'
                      - type: 'null'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: getV1LandlordsById
      x-operation-id-source: derived
    patch:
      summary: 'Change a landlord, archived or not: only the fields given change; `contact` is…'
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 200
                isEntity:
                  type: boolean
                plaintiffType:
                  anyOf:
                  - type: string
                    enum:
                    - individual
                    - corporation
                    - llc
                    - partnership
                    - trust
                    - estate
                    - other
                  - type: 'null'
                ownerOfRecord:
                  type: string
                  minLength: 1
                  maxLength: 200
                contact:
                  type: object
                  properties:
                    address:
                      type: string
                      minLength: 1
                      maxLength: 500
                    phone:
                      type: string
                      minLength: 1
                      maxLength: 40
                    email:
                      type: string
                      maxLength: 254
                      format: email
                      pattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
                  required:
                  - address
                  - phone
                  additionalProperties: false
                notes:
                  anyOf:
                  - type: string
                    maxLength: 1000
                  - type: 'null'
              additionalProperties: false
      responses:
        '200':
          description: The landlord as it now is.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Landlord'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: patchV1LandlordsById
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
  /v1/landlords/{id}/archive:
    post:
      summary: 'Archive a landlord: its cases and charges stay, and it can no longer be chosen…'
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The landlord.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Landlord'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: postV1LandlordsByIdArchive
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
  /v1/landlords/{id}/unarchive:
    post:
      summary: Unarchive a landlord, so it can be chosen for a new case again.
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The landlord.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Landlord'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: postV1LandlordsByIdUnarchive
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
  /v1/landlords/{id}/documents:
    post:
      summary: 'Upload the landlord''s management agreement: a PDF, JPEG or PNG of at most 10…'
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filename:
                  type: string
                  minLength: 1
                  maxLength: 255
                contentBase64:
                  type: string
                  minLength: 1
                purpose:
                  type: string
                  const: management_agreement
              required:
              - filename
              - contentBase64
              additionalProperties: false
      responses:
        '201':
          description: The stored agreement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LandlordDocument'
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: postV1LandlordsByIdDocuments
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
  /v1/landlords/{id}/documents/{docId}:
    get:
      summary: Download one of the landlord's files.
      security:
      - ApiKey: []
      - SessionToken: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: docId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The file's bytes, with the stored `Content-Type` (`application/pdf`, `image/jpeg` or `image/png`), as an attachment.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '400':
          description: The request is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The credential is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'The credential is not allowed to do this (`forbidden`). For a signed-in session: `permission_denied`, the person''s role in the organization lacks the permission this needs (ask an owner); `no_organization`, the person belongs to no organization yet (start one with `POST /v1/me/organizations` or accept an invitation).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'The request conflicts with the current state: for a case, it is not in a state that allows this, or its details were erased (`erased`); for an API key, a limit or the key in use.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The case did not pass a check.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Landlords
      operationId: getV1LandlordsByIdDocumentsByDocId
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
components:
  schemas:
    LandlordDocument:
      type: object
      description: A landlord's management agreement, without its contents. A PDF, JPEG or PNG, decided from the file's first bytes.
      required:
      - id
      - filename
      - contentType
      - uploadedAt
      properties:
        id:
          type: string
        filename:
          type: string
        contentType:
          enum:
          - application/pdf
          - image/jpeg
          - image/png
        uploadedAt:
          type: string
          format: date-time
    Landlord:
      type: object
      description: 'An owner the organization acts for, as a property manager: a profile reused across cases, never an account. It belongs to the organization, whatever the mode, and only live cases take one: a live key and a signed-in person see it, a test key never does. An archived landlord keeps its cases and is hidden from `GET /v1/landlords` unless `includeArchived=true`. At most 1,000 per organization, archived ones included.'
      required:
      - id
      - name
      - isEntity
      - plaintiffType
      - ownerOfRecord
      - contact
      - notes
      - archived
      - caseCount
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
        name:
          type: string
        isEntity:
          type: boolean
          description: A company, trust or other entity rather than a person.
        plaintiffType:
          enum:
          - individual
          - corporation
          - llc
          - partnership
          - trust
          - estate
          - other
          - null
          description: The legal type of the plaintiff, as the full service asks it; null when not given.
        ownerOfRecord:
          type: string
          description: The owner of record of the properties; the name unless given.
        contact:
          type: object
          required:
          - address
          - phone
          - email
          properties:
            address:
              type: string
            phone:
              type: string
            email:
              type:
              - string
              - 'null'
              format: email
        notes:
          type:
          - string
          - 'null'
          description: The organization's own notes; never on a court document.
        archived:
          type: boolean
        caseCount:
          type: integer
          description: How many of the organization's cases in the key's mode name this landlord.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - details
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: An organization API key (`eak_test_...` or `eak_live_...`).
    SessionToken:
      type: http
      scheme: bearer
      description: 'A session token (`ess_...`) from `POST /v1/auth/signup` or `/v1/auth/login`, valid for 30 days. On the case, webhook, API key and organization routes it acts for the organization the session is in (`POST /v1/me/organization` switches it) in the mode named by the `X-Evictions-Mode` header: `test` (the default) or `live`.'
    AttorneyToken:
      type: http
      scheme: bearer
      description: A user token (`eut_...`) of a verified attorney.
externalDocs:
  url: https://evictionsapi.com/docs
x-refined-from:
- api.evictionsapi.com.json
- evictionsapi-com-api-evictions-openapi.json
- evictionsapi-com-openapi.json