Procurify departments API

openapi: 3.0.3
info:
  title: Procurify API Documentation account-codes departments API
  version: ''
  description: '

    # Disclaimer


    - Procurify’s API is evolving and is subject to change at any time. Additionally, aspects of the API are undocumented, including certain methods, events, and properties. Given that both documented and undocumented aspects of the Procurify API may change at any time, the client relies on the API at their own risk.

    - Client (and/or client’s representative) is responsible for building, testing, and maintaining any API connection between Procurify and any other tool.  Procurify’s responsibility strictly involves providing support on clarifications in regards to the issued API document.

    - Procurify’s API is offered on an “as is” and “as available” basis, without warranties of any kind. By accepting this agreement, you agree that you have read the current API documentation, and accept the API functionality in its current state including current limitations. For questions and clarification around the documentation, please contact support@procurify.com.

    - In accordance with Section 2.(b) of our Subscription Services Agreement, Procurify reserves the right to deny access to our API at any time. If your API requests are too large and time out, contact us immediately to avoid possible suspension of access.

    - You may not attempt to reverse engineer or otherwise derive source code, trade secrets, or know-how in the Procurify API or portion thereof. You may not use the Procurify API to replicate or compete with core products or services offered by Procurify.

    '
servers:
- url: https://{user_domain}.procurify.com
  description: Your Procurify domain
  variables:
    user_domain:
      default: your-domain
      description: Your procurify domain
tags:
- name: departments
paths:
  /api/v3/departments/:
    get:
      operationId: departments_list
      description: ' '
      summary: List Departments
      parameters:
      - in: query
        name: branch
        schema:
          type: integer
        description: Filter departments by their branch.
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - in: query
        name: include_is_active_for_account_code
        schema:
          type: integer
        description: Setting this adds the addition of the booeal field 'has_active_account' to each department object of the response. The query param accepts an integer representing the primary key of the account code to check if there exists an account object associated with the department with that account code.
      - in: query
        name: location_perm_override
        schema:
          type: boolean
        description: Setting this overrides the need to enable the PROCUREMENT_ACCESS and/or RECEIVE_BY_DEPARTMENT feature switches. This parameter can only be used in conjunction with permission and user and cannot function without both of those parameters explicitly set.
      - in: query
        name: locations
        schema:
          type: array
          items:
            type: integer
        description: Filter departments by the locations (branches) passed in.
      - name: order_by
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: permission
        schema:
          type: integer
        description: Filter by permission. In isolation, this parameter can only be set to 68 (add purchase order); 841 (view report); or 899 (receive_po), which correlate with permission to add purchase orders, view reports, and receive purchase orders respectively. However, the results returned correlate with the “by department” version of these permissions, which means that results are filtered by permission to add purchase orders by department, permission to view reports by department, and receive purchase orders by department. This should only be used in conjunction with the PROCUREMENT_ACCESS and/or RECEIVE_BY_DEPARTMENT feature switches. If used in conjunction with location_perm_override=true and user, the value can be set to any permission, and the result will be departments filtered by the provided user and permission values. If used in conjunction with the RECEIVE_BY_DEPARTMENT feature flag, the permission can only be set to 68, 841, or 899 (see second sentence for what these permissions do). The result will be all departments filtered by the provided user value.
      - in: query
        name: requestable
        schema:
          type: string
        description: Fetch all requestable departments by the currently authorized user. Accepts ORDER, EXPENSE, TRAVEL, and PAY_REQUEST.
      - name: search
        required: false
        in: query
        description: A search term.
        schema:
          type: string
      - in: query
        name: user
        schema:
          type: integer
        description: Filter by user. If this parameter is set, the user must be a superuser or have the add_po_by_department or receive_po_by_department permissions. In isolation, this parameter should only be used in conjunction with the PROCUREMENT_ACCESS and/or RECEIVE_BY_DEPARTMENT feature switches. If used in conjunction with location_perm_override=true and permission query parameter, the result returned will be departments filtered by the provided user and permission values. If used in conjunction with the RECEIVE_BY_DEPARTMENT feature flag, the result will be departments filtered by the user provided and the permission set to 68 (add purchase order); 841 (view report); or 899 (receive purchase order) (see permission query parameter explanation for more information on what these stand for).
      tags:
      - departments
      security:
      - RemoteAuthentication: []
      - M2MAuthentication: []
      - BasicAuthentication: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDepartmentReadList'
            text/csv:
              schema:
                $ref: '#/components/schemas/PaginatedDepartmentReadList'
          description: ''
    post:
      operationId: departments_create
      description: ' '
      summary: Create New Department
      parameters:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      tags:
      - departments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          ? ''
          : schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
        required: true
      security:
      - RemoteAuthentication: []
      - M2MAuthentication: []
      - BasicAuthentication: []
      - cookieAuth: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepartmentReadSerializerSingleCreate'
            text/csv:
              schema:
                $ref: '#/components/schemas/DepartmentReadSerializerSingleCreate'
          description: ''
  /api/v3/departments/{id}/:
    put:
      operationId: departments_update
      description: ' '
      summary: Update Department
      parameters:
      - in: query
        name: format
        schema:
          type: string
          enum:
          - csv
          - json
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this department.
        required: true
      tags:
      - departments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          ? ''
          : schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          application/xml:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DepartmentUpsertRequest'
        required: true
      security:
      - RemoteAuthentication: []
      - M2MAuthentication: []
      - BasicAuthentication: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepartmentReadSerializerSingleUpdate'
            text/csv:
              schema:
                $ref: '#/components/schemas/DepartmentReadSerializerSingleUpdate'
          description: ''
components:
  schemas:
    PaginatedDepartmentReadList:
      type: object
      properties:
        metadata:
          type: object
          properties:
            pagination:
              type: object
              properties:
                count:
                  type: integer
                  example: 10
                next:
                  type: string
                  nullable: true
                  format: uri
                  example: null
                previous:
                  type: string
                  nullable: true
                  format: uri
                  example: null
                page_size:
                  type: integer
                  example: 10
                num_pages:
                  type: integer
                  example: 1
                current_page:
                  type: integer
                  example: 1
          example:
            pagination:
              count: 10
              next: null
              previous: null
              page_size: 10
              num_pages: 1
              current_page: 1
        data:
          type: array
          items:
            $ref: '#/components/schemas/DepartmentRead'
    DepartmentRead:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        branch:
          $ref: '#/components/schemas/LocationSimple'
        external_id:
          type: string
          nullable: true
          description: External id
          maxLength: 100
        name:
          type: string
          maxLength: 150
        active:
          type: boolean
        punchout_email:
          type: string
          nullable: true
        is_active_for_account_code:
          type: boolean
          readOnly: true
      required:
      - branch
      - name
    LocationSimple:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 150
        headquarter:
          type: boolean
          readOnly: true
      required:
      - name
    DepartmentReadSerializerSingleUpdate:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties: {}
          default: {}
        data:
          $ref: '#/components/schemas/DepartmentRead'
      required:
      - data
    DepartmentUpsertRequest:
      type: object
      properties:
        branch:
          type: integer
        external_id:
          type: string
          nullable: true
          description: External id
          maxLength: 100
        name:
          type: string
          minLength: 1
          maxLength: 150
        active:
          type: boolean
        punchout_email:
          type: string
          nullable: true
          minLength: 1
      required:
      - branch
      - name
    DepartmentReadSerializerSingleCreate:
      type: object
      properties:
        metadata:
          type: object
          additionalProperties: {}
          default: {}
        data:
          $ref: '#/components/schemas/DepartmentRead'
      required:
      - data
  securitySchemes:
    BasicAuthentication:
      type: http
      scheme: basic
    M2MAuthentication:
      type: http
      scheme: bearer
      bearerFormat: JWT
    RemoteAuthentication:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://<your-domain>.procurify.com/oauth/authorize
          tokenUrl: https://<your-domain>.procurify.com/oauth/token
          scopes: {}
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid