openapi: 3.0.3
info:
  title: Partner API
  description: Management of Partners in epilot
  version: 1.0.0
tags:
- name: partners
  x-displayName: Partners
  description: Partner operations
- name: partner_schema
  x-displayName: Partner
  description: |
    <SchemaDefinition schemaRef="#/components/schemas/Partner" />
x-tagGroups:
- name: APIs
  tags:
  - partners
- name: Schemas
  tags:
  - partner_schema
security:
- EpilotAuth: []
- AsOrganization: []
paths:
  /v1/partners/{id}/approve:
    post:
      operationId: approvePartner
      summary: approvePartner
      tags:
      - partners
      description: Approve partner request
      parameters:
      - in: path
        name: id
        schema:
          $ref: '#/components/schemas/PartnerId'
        required: true
        description: The Id of partner
      responses:
        '201':
          description: Approve successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partner'
        '400':
          description: Unable to approve
  /v1/partners/{id}/reject:
    post:
      operationId: rejectPartner
      summary: rejectPartner
      tags:
      - partners
      description: Reject partner request
      parameters:
      - in: path
        name: id
        schema:
          $ref: '#/components/schemas/PartnerId'
        required: true
        description: The Id of partner
      responses:
        '200':
          description: Invited successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partner'
        '400':
          description: Unable to reject
  /v1/partners/assignables:search:
    post:
      operationId: searchAssignable
      summary: searchAssignables
      description: |
        Search for assignable users/organizations from this organization and Partners

        Results can include:
         - Users in your organization
         - Users in partner organizations
         - Partner organizations
      tags:
      - partners
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  description: search query to filter results
                  type: string
                  default: ''
                from:
                  description: start results from an offset for pagination
                  type: integer
                  minimum: 0
                  default: 0
                size:
                  description: limit number of results to return
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 25
                org_ids:
                  description: filter results to specific organizations. defaults to all orgs
                  type: array
                  items:
                    $ref: '#/components/schemas/OrganizationId'
                portalUsersEntityIdScope:
                  description: Optional parameter if 'types' contains 'ecp' type user. Portal Users will only be fetched in the context of an entity, fetching the related ones through relations and not returning placeholders anymore.
                  type: string
                  default: ''
                types:
                  description: filter results to specific types of assignables. defaults to all types
                  type: array
                  default:
                  - user
                  - partner_user
                  - partner_organization
                  - ecp
                  - group
                  items:
                    type: string
                    enum:
                    - user
                    - partner_user
                    - partner_organization
                    - ecp
                    - group
              required:
              - q
      responses:
        '200':
          description: List of assignable results
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    description: total number of search results
                    type: integer
                    example: 25
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Assignable'
  /v1/partners/assignables:batchGet:
    post:
      operationId: batchGetAssignable
      summary: batchGet
      description: |
        Search for assignable users from this organization by its ids
      tags:
      - partners
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                minItems: 1
                type: object
                properties:
                  user_id:
                    description: user id of assignable
                    type: string
                  org_id:
                    description: organization id of assignable (optional, defaults to caller org)
                    type: string
                  group_id:
                    description: group id of assignable (optional)
                    type: string
      responses:
        '200':
          description: List of assignable results
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    description: total number of search results
                    type: integer
                    example: 25
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Assignable'
  /v1/partner-directory/public/getPartnerByToken:
    get:
      operationId: getPartnerByToken
      summary: getPartnerByToken
      description: Get partner by token
      security: []
      tags:
      - partners
      parameters:
      - in: query
        name: token
        schema:
          $ref: '#/components/schemas/InviteToken'
        required: true
        description: Invite Token
      responses:
        '200':
          description: Partner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partner'
        '404':
          description: Token not found for the partner
  /v1/partner-directory/public/activate:
    post:
      operationId: activatePartner
      summary: activatePartner
      description: Activate partner using an invite token
      security: []
      tags:
      - partners
      parameters:
      - name: token
        description: Invite Token
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/InviteToken'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivatePartnerPayload'
      responses:
        '200':
          description: Activated successfully
        '404':
          description: Token not found for the partner
  /v1/geolocation/text:search:
    post:
      operationId: searchGeolocationForText
      summary: searchGeolocationForText
      tags:
      - partners
      description: Converts a given string, in the format of an address, to geo-location latitude and longitude
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchGeolocation'
      responses:
        '200':
          description: Geo-location converted from text
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Geolocation'
        '400':
          description: No text provided
        '404':
          description: No geo-location found for text
  /v2/partners/{id}/invite:
    post:
      operationId: invitePartnerV2
      summary: invitePartnerV2
      tags:
      - partners
      description: Invite a partner into collaboration. It will send an email to partner and ask to join into collaboration
      parameters:
      - in: path
        name: id
        schema:
          $ref: '#/components/schemas/PartnerId'
        required: true
        description: The Id of partner
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerInvitationPayload'
      responses:
        '200':
          description: Invited successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Partner'
        '400':
          description: Unable to invite
components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    AsOrganization:
      type: apiKey
      in: header
      name: x-ivy-org-id
      description: Set organization id when using internal auth
  schemas:
    InviteToken:
      type: string
    Partner:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/PartnerId'
        organization_id:
          $ref: '#/components/schemas/OrganizationId'
        created_at:
          type: string
          example: '2022-02-08T04:44:32.246Z'
        description:
          type: string
          description: Description
          example: Description
        company_name:
          type: string
          description: Company name
          example: Company name
        invitation_token:
          description: Invitation token
          type: string
        invitation_email:
          deprecated: true
          description: Email using to receive invitation
          type: string
          format: email
        email:
          description: Email using to receive invitation
          type: string
          format: email
        signed_up_email:
          description: Email using to sign up
          type: string
          format: email
        partner_org_id:
          description: Target Organization
          type: string
          example: 123456
        status:
          type: string
          enum:
          - Pending
          - Request
          - Deleted
          - Invited
          - Rejected
    PartnerId:
      type: string
      example: e45a6dc2-3795-43a3-ae0f-6b6760f310fc
    OrganizationId:
      type: string
      example: '123'
    ActivatePartnerPayload:
      type: object
      properties:
        company_name:
          type: string
          description: Company name
          example: Company name
        signed_up_email:
          description: Email using to sign up
          type: string
          format: email
        organization_id:
          description: organization id
          type: string
      required:
      - signed_up_email
      - organization_id
    PartnerInvitationPayload:
      type: object
      properties:
        language:
          type: string
          description: Language for partner invitation email
          enum:
          - en
          - de
          default: en
    Assignable:
      oneOf:
      - $ref: '#/components/schemas/AssignableUser'
      - $ref: '#/components/schemas/AssignablePartnerUser'
      - $ref: '#/components/schemas/AssignableOrganization'
      - $ref: '#/components/schemas/AssignableEcpPlaceholder'
      - $ref: '#/components/schemas/AssignableGroup'
    BaseAssignable:
      type: object
      properties:
        type:
          type: string
          example: user
        display_name:
          type: string
          example: Example User
        image_uri:
          type: object
          properties:
            original:
              type: string
              format: uri
              example: https://epilot-staging-user-content.s3.eu-central-1.amazonaws.com/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png
            thumbnail_32:
              type: string
              format: uri
              example: https://file.sls.epilot.io/v1/files/public/preview?w=32&h=32&key=/728/8043d909-71fc-4838-a363-1b15dc1d585c/epilot.png
          required:
          - original
        org_id:
          $ref: '#/components/schemas/OrganizationId'
      required:
      - type
      - display_name
      - org_id
    AssignableUser:
      allOf:
      - $ref: '#/components/schemas/BaseAssignable'
      - type: object
        properties:
          type:
            type: string
            enum:
            - user
            example: user
          display_name:
            type: string
            example: Example User
          user_id:
            type: string
            example: '456'
    AssignablePartnerUser:
      allOf:
      - $ref: '#/components/schemas/BaseAssignable'
      - type: object
        properties:
          type:
            type: string
            enum:
            - partner_user
            example: partner_user
          display_name:
            type: string
            example: Example Partner User
          partner_id:
            $ref: '#/components/schemas/PartnerId'
          user_id:
            type: string
            example: '456'
    AssignableGroup:
      allOf:
      - $ref: '#/components/schemas/BaseAssignable'
      - type: object
        properties:
          group_id:
            type: string
            example: '456'
    AssignableOrganization:
      allOf:
      - $ref: '#/components/schemas/BaseAssignable'
      - type: object
        properties:
          type:
            type: string
            enum:
            - partner_organization
            example: partner_organization
          display_name:
            type: string
            example: Example Partner Organization
          partner_id:
            $ref: '#/components/schemas/PartnerId'
          email:
            type: string
            example: Email of Partner Organization
          geolocations:
            type: array
            items:
              $ref: '#/components/schemas/AddressGeolocation'
          phone:
            type: string
            example: Phone number of Partner
          activity_radius:
            type: number
            description: Activity radius, in km, the partner is operating in
            example: 50
        required:
        - type
        - display_name
        - partner_id
    AssignableEcpPlaceholder:
      allOf:
      - $ref: '#/components/schemas/BaseAssignable'
      - type: object
        properties:
          type:
            type: string
            enum:
            - ecp
            example: ecp
          display_name:
            type: string
            example: Example Ecp Placeholder
          user_id:
            type: string
            example: '456'
          email:
            type: string
            example: Email of ECP Placeholder
        required:
        - type
        - display_name
        - user_id
    SearchGeolocation:
      type: object
      properties:
        address:
          type: string
          description: Address text to convert into geolocation coordinates
          example: Auweg 1, 93055 Regensburg, DE
      required:
      - address
    Geolocation:
      type: object
      properties:
        lat:
          type: number
          description: Latitude
          example: 49.013
        lng:
          type: number
          description: Longitude
          example: 12.101
        addressLabel:
          type: string
          description: Full address label as returned by the location service
        relevance:
          type: number
          description: Relevance of the result. A number between 0 and 1. Closer to 1 means more relevant
      required:
      - lat
      - lng
    Address:
      type: object
      properties:
        street:
          type: string
          description: Street
          example: Auweg
        street_number:
          type: string
          description: Street
          example: '10'
        city:
          type: string
          description: City
          example: Regensburg
        postal_code:
          type: string
          description: Postal code
          example: '93055'
        country:
          type: string
          description: Country
          example: DE
    AddressGeolocation:
      type: object
      allOf:
      - type: object
        properties:
          address:
            $ref: '#/components/schemas/Address'
      - $ref: '#/components/schemas/Geolocation'
      required:
      - address
servers:
- url: https://partner-directory-api.sls.epilot.io

