evictionsapi-com Invitations API

openapi: 3.2.0
info:
  title: Evictionsapi Com Invitations API
  version: 0.0.0
  contact:
    email: hello@evictionsapi.com
  description: 'Operations tagged Invitations 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: Invitations
paths:
  /v1/invitations/{token}:
    get:
      summary: 'An invitation, from the link in its email: the organization, the role and the…'
      security: []
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The invitation. `accountExists` says whether the invited address already has an account (then the person signs in to accept).
          content:
            application/json:
              schema:
                type: object
                required:
                - organizationName
                - role
                - emailMasked
                - accountExists
                properties:
                  organizationName:
                    type: string
                  role:
                    enum:
                    - owner
                    - member
                    - viewer
                  emailMasked:
                    type: string
                    description: The first letter and the domain of the invited address, such as `s•••@example.com`.
                  accountExists:
                    type: boolean
        '404':
          description: '`invitation_invalid`: the token is unknown, already used, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many requests from this address: at most 30 every 10 minutes, counting both invitation endpoints. `Retry-After` gives the seconds to wait.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Invitations
      operationId: getV1InvitationsByToken
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
  /v1/invitations/{token}/accept:
    post:
      summary: Accept an invitation.
      security:
      - {}
      - SessionToken: []
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 120
                password:
                  type: string
                  minLength: 10
                  maxLength: 200
              required:
              - name
              - password
              additionalProperties: false
      responses:
        '201':
          description: A new session for a new account (`token`, shown here only), with the account view; 200 with the account view alone for a signed-in person. An `Idempotency-Key` header is ignored.
          content:
            application/json:
              schema:
                type: object
                required:
                - token
                - user
                - organization
                - role
                - permissions
                - organizations
                - modes
                properties:
                  token:
                    type: string
                    description: 'A session token (`ess_...`), shown here only. Send it as `Authorization: Bearer`.'
                  user:
                    type: object
                    required:
                    - id
                    - name
                    - email
                    - role
                    - emailConfirmed
                    - hasPassword
                    - googleLinked
                    properties:
                      id:
                        type: string
                      name:
                        type:
                        - string
                        - 'null'
                      email:
                        type: string
                      role:
                        enum:
                        - customer
                        - attorney
                        - platform_admin
                        description: The kind of account. The person's role in an organization is the top-level `role`.
                      emailConfirmed:
                        type: boolean
                        description: 'Whether the person confirmed this address (with the emailed link, or by signing in with Google). Nothing depends on it: an unconfirmed account works the same.'
                      hasPassword:
                        type: boolean
                        description: Whether the account has a password (an account made with Google has none until one is set).
                      googleLinked:
                        type: boolean
                        description: Whether a Google account is linked, so the person can sign in with Google.
                  organization:
                    type:
                    - object
                    - 'null'
                    description: The organization this session acts for; null when the person belongs to none.
                    required:
                    - id
                    - name
                    - verified
                    - kind
                    - contactEmail
                    - contactPhone
                    - contactAddress
                    - billingEmail
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      verified:
                        type: boolean
                      kind:
                        enum:
                        - owner
                        - property_manager
                        - both
                        - null
                        description: Whether the organization owns the rentals, manages them for others, or both; null when not said.
                      contactEmail:
                        type:
                        - string
                        - 'null'
                      contactPhone:
                        type:
                        - string
                        - 'null'
                      contactAddress:
                        type:
                        - string
                        - 'null'
                      billingEmail:
                        type:
                        - string
                        - 'null'
                  role:
                    enum:
                    - owner
                    - member
                    - viewer
                    - custom
                    - platform_admin
                    - null
                    description: 'The person''s role in that organization (the platform''s operator: `platform_admin`); null without an organization.'
                  permissions:
                    type: array
                    items:
                      enum:
                      - cases.write
                      - billing.pay
                      - billing.manage
                      - keys.test
                      - integrations.manage
                      - organization.manage
                      - people.manage
                      - landlords.write
                    description: What the person may change in that organization. Reading needs no permission. Empty without an organization.
                  organizations:
                    type: array
                    description: Every organization the person belongs to, oldest membership first.
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - kind
                      - role
                      - caseEmails
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        kind:
                          enum:
                          - owner
                          - property_manager
                          - both
                          - null
                        role:
                          enum:
                          - owner
                          - member
                          - viewer
                          - custom
                        caseEmails:
                          enum:
                          - all
                          - mine
                          - none
                          description: 'Which of the organization''s case emails the person gets: all, only cases they opened, or none (`PATCH /v1/me/organizations/:id`).'
                  modes:
                    type: object
                    required:
                    - test
                    - live
                    description: The modes this server offers. `test` is always true.
                    properties:
                      test:
                        type: boolean
                      live:
                        type: boolean
        '400':
          description: '`invalid_request`: signed out, the body needs `name` and a `password` of 10 to 200 characters (`details.issues` names them).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: '`unauthenticated`: an `Authorization` header was sent and is not a valid session.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: '`account_kind`: an attorney''s or the operator''s account cannot join an organization. `forbidden`: an API key, or a disabled account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '`invitation_invalid`: the token is unknown, already used, revoked or expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '`invitation_email_mismatch`: the session is for another address. `email_taken`: signed out, and the invited address already has an account; sign in to accept. `already_member`: the person is a member already. `member_limit`: the organization already has 50 people. Nothing was created and the invitation is still pending.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: The request body is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many requests from this address: at most 30 every 10 minutes, counting both invitation endpoints. `Retry-After` gives the seconds to wait.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '`busy`: too many password checks are waiting. Nothing was created. `Retry-After: 5` gives the seconds to wait.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Invitations
      operationId: postV1InvitationsByTokenAccept
      x-operation-id-source: derived
    servers:
    - url: https://api.evictionsapi.com
components:
  schemas:
    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