Rhumbix Batch Import API

openapi: 3.2.0
info:
  version: 1.0.1
  description: "The Rhumbix API is intended for use by Rhumbix customers and partners to build integrations with the Rhumbix application. The API is designed to support regular updates and queries in batch requests. Rhumbix primarily manages data for construction workers in the field. Integrations should be aware that updates to this data will directly influence the users of the mobile and web application. For access to the API, contact your Rhumbix support representitive. Further application documentation and support can be found at https://rhumbix.desk.com/ \n## Overview\nThe usual order of operation is like this: \n1) You post data to the API with your unique company_key and x-api-key. \n2) The request is put into a queue of requests (sometimes requests are very large) and you receive back a batch_key to check the status of your request. \n3) You check the unique URL of your request using your new batch_key, your company_key and x-api-key until its status is COMPLETE. \n### Base URL \nhttps://async-api.rhumbix.com/V1_0_1\n# Authentication\nAuthentication is handled via a token system and a unique company_key. You can create a company_key and retrieve an api token key by logging in to the Rhumbix web platform. Once you have an access token, you can interact with the API by including the `x-api-key` in the header of an HTTP `GET` or `POST` request.\n```json\n{\n  \"x-api-key\": \"abcdefghijklmnopqrstuvwxyz0123456789\" \n}\n```"
  x-logo:
    url: https://s3.amazonaws.com/rmbx-export-assets/rmbx_horizontal_logo_colored.png
  title: Rhumbix Public Batch Export Batch Import API
servers:
- url: https://async-api.rhumbix.com
tags:
- name: Batch Import
  description: Import Data into Rhumbix
paths:
  /{company_key}/batch/employee/import:
    post:
      description: Post a new batch of employee data for import into Rhumbix. Returns a new batch_key for subsequently retrieving status updates for this batch.
      parameters:
      - description: The unique company key associated with your api key.
        required: true
        name: company_key
        in: path
        schema:
          type: string
      tags:
      - Batch Import
      summary: Employee Batch Data
      security:
      - RMBXApiAuthorizer: []
      - api_key: []
      operationId: batchEmployeeImport
      x-code-samples:
      - lang: Shell
        source: "curl -X POST -H \"Content-Type: application/json\" \\\n-H \"x-api-key: foobarbazbuz\" \\\n-d '[{\"company_supplied_id\": \"alexa\", \"user_role\": \"WORKER\", \n\"first_name\": \"Alex\", \"last_name\": \"Alexander\"}]' \\\nhttps://async-api.rhumbix.com/V1_0_1/greatco/batch/employee/import\n# {'batch_key': '1234abcd-56ef-gh78-ijkl-mnopqrstuvwx90'}"
      - lang: Python
        source: "import requests\ndata = [\n    {\n        'company_supplied_id': 'alexa', \n        'user_role': 'WORKER', \n        'first_name': 'Alex', \n        'last_name': 'Alexander'\n    }\n]\n\nheaders = {\n    'x-api-key': 'foobarbazbuz', \n    'Accept': 'application/json', \n    'Content-Type': 'application/json'\n}\n\ncompany_key = 'greatco'\nurl = 'https://async-api.rhumbix.com/V1_0_1/{}'\\\n      '/batch/employee/import'.format(company_key)\nresult = requests.post(url, headers=headers, json=data)\nprint result.json() \n# {'batch_key': '1234abcd-56ef-gh78-ijkl-mnopqrstuvwx90'}"
      responses:
        '200':
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          description: batch successfully posted
          content:
            application/json:
              schema:
                title: BatchEmployeeImportResponse
                type: object
                example:
                  batch_key: 1234abcd-56ef-gh78-ijkl-mnopqrstuvwx90
                properties:
                  batch_key:
                    $ref: '#/components/schemas/BatchKey'
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/Employee'
              type: array
              example:
              - first_name: Tom
                last_name: Tomson
                company_supplied_id: TOM01
                classification: apprentice
                is_active: true
                user_role: WORKER
                trade: carpenter
                phone: '9876543210'
                project_job_numbers:
                - '73617665666572726973'
                email: tomt@company.com
              - first_name: John
                last_name: Johnson
                company_supplied_id: JON02
                classification: ''
                is_active: true
                user_role: FOREMAN
                trade: ''
                phone: '9876543211'
                project_job_numbers:
                - '73617665666572726973'
                - '7468652064756465'
                email: johnj@company.com
              title: BatchEmployeeImportRequest
        description: An object that contains employee data that you would like to import into Rhumbix.
        required: true
  /{company_key}/batch/project/import:
    post:
      description: Post a new batch of project data to import into Rhumbix. Returns the new batch_key for subsequently retrieving status updates for this batch.
      parameters:
      - description: The unique company key associated with your api key.
        required: true
        name: company_key
        in: path
        schema:
          type: string
      tags:
      - Batch Import
      summary: Project Batch Data
      security:
      - RMBXApiAuthorizer: []
      - api_key: []
      operationId: batchProjectImport
      x-code-samples:
      - lang: Shell
        source: "curl -X POST -H \"Content-Type: application/json\" \\\n-H \"x-api-key: foobarbazbuz\" \\\n-d '[{\"job_number\": \"7468652064756465\", \"name\": \"Hollywood Star Lanes\",\n\"address\": \"5227 Santa Monica Boulevard, Los Angeles, CA 90029\",\n\"cost_codes\": [{\"code\": \"18-10048\",\"description\": \"Plumbing\",\"units\": \n\"feet\"}, {\"code\": \"18-10012\",\"description\": \"Heating\",\"units\": \"\"}]}, \n{\"job_number\": \"73617665666572726973\",\"name\": \"Chez Quis\", \n\"description\": \"High End Restaurant where Abe Froman Eats.\", \n\"address\": \"22 W Schiller St, Chicago, IL 60610\",\"cost_codes\": []}]' \\\nhttps://async-api.rhumbix.com/V1_0_1/greatco/batch/project/import\n# {'batch_key': '1234abcd-56ef-gh78-ijkl-mnopqrstuvwx90'}"
      - lang: Python
        source: "import requests\ndata = [\n    {\n        'job_number': '7468652064756465', \n        'name': 'Hollywood Star Lanes',\n        'description': '',\n        'address': '5227 Santa Monica Boulevard, Los Angeles, CA 90029',\n        'cost_codes': [\n            {\n                'code': '18-10048',\n                'description': 'Plumbing',\n                'units': 'feet'\n            },\n            {\n                'code': '18-10012',\n                'description': 'Heating',\n                'units': ''\n            }\n        ]\n    },\n    {\n        'job_number': '73617665666572726973',\n        'name': 'Chez Quis',\n        'description': 'High End Restaurant where Abe Froman Eats.',\n        'address': '22 W Schiller St, Chicago, IL 60610',\n        'cost_codes': []\n    }\n]\n\nheaders = {\n    'x-api-key': 'foobarbazbuz', \n    'Accept': 'application/json', \n    'Content-Type': 'application/json'\n}\n\ncompany_key = 'greatco'\nurl = 'https://async-api.rhumbix.com/V1_0_1/{}'\\\n      '/batch/project/import'.format(company_key)\nresult = requests.post(url, headers=headers, json=data)\nprint result.json() \n# {'batch_key': '1234abcd-56ef-gh78-ijkl-mnopqrstuvwx90'}"
      responses:
        '200':
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          description: batch successfully posted
          content:
            application/json:
              schema:
                title: BatchProjectImportResponse
                type: object
                example:
                  batch_key: 1234abcd-56ef-gh78-ijkl-mnopqrstuvwx90
                properties:
                  batch_key:
                    $ref: '#/components/schemas/BatchKey'
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/Project'
              type: array
              example:
              - status: INACTIVE
                description: New Bowling Alley
                cost_codes:
                - code: 18-10048
                  group: '18'
                  description: Plumbing
                  is_active: true
                  erp_units: feet
                  units: percent complete
                - units: ''
                  is_active: true
                  code: 18-10012
                  group: '18'
                  description: Heating
                address: 5227 Santa Monica Boulevard, Los Angeles, CA 90029
                job_number: '7468652064756465'
                name: Hollywood Star Lanes
              - status: ACTIVE
                description: High End Restaurant where Abe Froman Eats.
                cost_codes:
                - units: ''
                  code: HF-669
                  is_active: true
                  description: Electrical Gear
                - units: meters
                  code: HF-770
                  is_active: true
                  description: Platform Conduit
                address: 22 W Schiller St, Chicago, IL 60610
                job_number: '73617665666572726973'
                name: Chez Quis
              title: BatchProjectImportRequest
        description: "An object that contains project data that you would like to import into Rhumbix. \n\n**Unique Constraints:** _[ Project + Code ]_  \n\n\n\nThe CostCode field `code` muse be unique within a Project. Do not pass in multiples of the same code. `description` **_can_** be an empty string: \"\". \n```json\n# This will ERROR because there are two \"10-200\" codes.\n{\n    \"job_number\": \"JOB314\",\n    \"name\": \"Mission Impossible\",\n    \"cost_codes\": [\n        {\n            \"code\": \"10-200\",\n            \"description\": \"Conduit\",\n            \"units\": \"feet\",\n            \"is_active\": true\n        },\n        {\n            \"code\": \"10-200\",\n            \"description\": \"Electrical\",\n            \"units\": \"meters\",\n            \"is_active\": false\n        }\n    ]\n}\n```"
        required: true
  /{company_key}/batch/employee/import/{batch_key}/status:
    get:
      responses:
        '200':
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          description: batch is PENDING (in-process) or COMPLETE
          content:
            application/json:
              schema:
                title: BatchEmployeeImportStatusResponse
                required:
                - status
                type: object
                example:
                  status: COMPLETE
                  errors:
                    ? ''
                    : company_supplied_id:
                      - This field is required.
                    BOB123:
                      phone:
                      - This field must be unique.
                      email:
                      - This field must be unique.
                    LARRY6:
                      project_job_numbers:
                        non_existant_ProjectABC:
                        - This job number does not exist.
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
                  employees:
                    items:
                      $ref: '#/components/schemas/EmployeeImportStatus'
                    type: array
            application/xml:
              schema:
                title: BatchEmployeeImportStatusResponse
                required:
                - status
                type: object
                example:
                  status: COMPLETE
                  errors:
                    ? ''
                    : company_supplied_id:
                      - This field is required.
                    BOB123:
                      phone:
                      - This field must be unique.
                      email:
                      - This field must be unique.
                    LARRY6:
                      project_job_numbers:
                        non_existant_ProjectABC:
                        - This job number does not exist.
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
                  employees:
                    items:
                      $ref: '#/components/schemas/EmployeeImportStatus'
                    type: array
        '403':
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          description: url does not exist yet but will when batch queues up
          content:
            application/json:
              schema:
                title: BatchStatusResponse
                required:
                - status
                type: object
                example:
                  status: ACCEPTED
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
            application/xml:
              schema:
                title: BatchStatusResponse
                required:
                - status
                type: object
                example:
                  status: ACCEPTED
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
      parameters:
      - required: true
        name: company_key
        in: path
        schema:
          type: string
      - required: true
        name: batch_key
        in: path
        schema:
          type: string
      tags:
      - Batch Import
      summary: Employee Import Status
      security:
      - RMBXApiAuthorizer: []
      - api_key: []
      operationId: batchEmployeeImportStatus
      description: Retrieve the processing status of a employee import batch using the batch_key value that was returned when the batch was created.  After creating a new import batch, you should poll this endpoint to monitor the status as your batch is processed asynchornously.  When the returned status is "Complete", the 'employees' property will contain a status, by id, of each item requested to be imported.  The status field on each item will indicate whether the item was UPDATED (merged into existing record in Rhumbix), CREATED (new record created in Rhumbix), or ERROR (check the 'details' property for more information on why the record was not created nor imported).  It is possible for some records to be created/updated succssfully while others fail.  Check the status on each row to ensure that every record was imported successfully or to handle errors appopriately.
  /{company_key}/batch/project/import/{batch_key}/status:
    get:
      responses:
        '200':
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          description: batch is PENDING (in-process) or COMPLETE
          content:
            application/json:
              schema:
                title: BatchProjectImportStatusResponse
                required:
                - status
                type: object
                example:
                  status: COMPLETE
                  errors:
                    ? ''
                    : job_number:
                      - This field may not be blank.
                    projectXYZ:
                      cost_codes:
                        ? ''
                        : code:
                          - This field may not be blank.
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
                  projects:
                    items:
                      $ref: '#/components/schemas/ProjectImportStatus'
                    type: array
            application/xml:
              schema:
                title: BatchProjectImportStatusResponse
                required:
                - status
                type: object
                example:
                  status: COMPLETE
                  errors:
                    ? ''
                    : job_number:
                      - This field may not be blank.
                    projectXYZ:
                      cost_codes:
                        ? ''
                        : code:
                          - This field may not be blank.
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
                  projects:
                    items:
                      $ref: '#/components/schemas/ProjectImportStatus'
                    type: array
        '403':
          description: url does not exist yet but will when batch queues up
          content:
            application/json:
              schema:
                title: BatchStatusResponse
                required:
                - status
                type: object
                example:
                  status: ACCEPTED
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
            application/xml:
              schema:
                title: BatchStatusResponse
                required:
                - status
                type: object
                example:
                  status: ACCEPTED
                properties:
                  status:
                    $ref: '#/components/schemas/BatchStatus'
      parameters:
      - required: true
        name: company_key
        in: path
        schema:
          type: string
      - required: true
        name: batch_key
        in: path
        schema:
          type: string
      tags:
      - Batch Import
      summary: Project Import Status
      security:
      - RMBXApiAuthorizer: []
      - api_key: []
      operationId: batchProjectImportStatus
      description: Retrieve the processing status of a project import batch using the batch_key value that was returned when the batch was created.  After creating a new import batch, you should poll this endpoint to monitor the status as your batch is processed asynchornously.  When the returned status is "Complete", the 'projects' property will contain a status, by id, of each item requested to be imported.  The status field on each item will indicate whether the item was UPDATED (merged into existing record in Rhumbix), CREATED (new record created in Rhumbix), or ERROR (check the 'details' property for more information on why the record was not created nor imported).  It is possible for some records to be created/updated succssfully while others fail.  Check the status on each row to ensure that every record was imported successfully or to handle errors appopriately.
components:
  schemas:
    BatchKey:
      type: string
      title: BatchKey
    ProjectImportStatus:
      title: ProjectImportStatus
      required:
      - job_number
      properties:
        job_number:
          type: string
      allOf:
      - $ref: '#/components/schemas/ImportStatus'
      - type: object
    Employee:
      required:
      - company_supplied_id
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        company_supplied_id:
          type: string
          description: Unique id for each employee
        classification:
          type: string
        is_active:
          type: boolean
        user_role:
          enum:
          - ADMIN
          - FOREMAN
          - PM
          - WORKER
          - OFFICE_STAFF
          type: string
        trade:
          type: string
        phone:
          type: string
        project_job_numbers:
          items:
            type: string
          type: array
        email:
          type: string
      title: Employee
    ImportStatus:
      required:
      - status
      properties:
        status:
          enum:
          - PENDING
          - CREATED
          - UPDATED
          - ERROR
          type: string
        detail:
          type: string
    Project:
      required:
      - job_number
      - name
      type: object
      properties:
        status:
          enum:
          - INACTIVE
          - ACTIVE
          type: string
        description:
          type: string
        cost_codes:
          items:
            required:
            - code
            - description
            type: object
            properties:
              code:
                type: string
              group:
                type: string
              description:
                type: string
              is_active:
                type: boolean
              erp_units:
                type: string
                description: Units, as tracked from an accounting perspective (i.e. "sq ft")
              units:
                type: string
                description: Units, as tracked from a field perspective (i.e. "percent complete")
            title: CostCode
          type: array
        address:
          type: string
        job_number:
          type: string
        name:
          type: string
      title: Project
    EmployeeImportStatus:
      title: EmployeeImportStatus
      required:
      - company_supplied_id
      properties:
        company_supplied_id:
          type: string
      allOf:
      - $ref: '#/components/schemas/ImportStatus'
      - type: object
    BatchStatus:
      enum:
      - NOT_FOUND
      - ACCEPTED
      - PROCESSING
      - COMPLETE
      - ERROR
      type: string
      title: BatchStatus
  securitySchemes:
    api_key:
      in: header
      type: apiKey
      example: abcdefghijklmnopqrstuvwxyz0123456789
      name: x-api-key
    RMBXApiAuthorizer:
      example: abcdefghijklmnopqrstuvwxyz0123456789
      type: apiKey
      name: x-api-key
      in: header
x-servers:
- url: //async-api.rhumbix.com/V1_0_1
  description: Server URL