Logo
Submit a request
Follow

Service Requests

Adding a Service Request

URL

https://app.bluefolder.com/api/1.0/serviceRequests/add.aspx

Request

<request>
   <serviceRequestAdd>
       <customerID></customerID>
       <customerContactID></customerContactID>
       <customerLocationID></customerLocationID>
       <description></description>
       <status></status>
       <assignedTo>
           <userID></userID>
           ...
       </assignedTo>
       <billable></billable>
       <category></category>
       <customFields>
           <customField name="field name"></customField>
           ...
       </customFields>
       <dueDate></dueDate>
       <notes></notes>
       <priority></priority>
       <purchaseOrderNo></purchaseOrderNo>
       <referenceNo></referenceNo>
       <serviceManagerID></serviceManagerID>
       <equipmentToService>
           <equipID></equipID>
           ...
       </equipmentToService>
       <notifyCustomer></notifyCustomer>
       <externalID></externalID>
   </serviceRequestAdd>
</request>
            
  • customerID - (required) numeric, must match an existing ID from a customer in your customer list
  • customerContactID - numeric, must match an existing contact ID. If not included, the customer's primary contact will be assigned
  • customerLocationID - numeric, must match an existing location ID. If not included, the customer's primary location will be assigned
  • description - string (100 char limit)
  • status - string (50 char limit)
  • assignedTo - designates the userIDs that are to be assigned to the Service Request
    • userID - numeric, must match an existing User ID in your user list
  • billable - boolean (true/false)
  • category - string (50 char limit)
  • customFields
    • customField - the "name" attribute must specify the exact name of a custom field in your account. The actual value included between the opening and closing "customField" element tags should be a string value, regardless of the custom field's "data type".
  • dueDate - datetime, must be in the format YYYY.MM.DD HH:MM AM
  • notes - string (no char limit)
  • priority - string (50 char limit)
  • purchaseOrderNo - string (25 char limit)
  • referenceNo - string (50 char limit)
  • serviceManagerID - numeric, must match an existing User ID in your user list
  • equipmentToService - designates the customer equipment items that are to be associated with the Service Request
    • equipID - string, must match the ID of an existing Equipment Item belonging the customer specified in the "customerID" element
  • notifyCustomer - boolean, indicates if customer should receive an email notification of the new Service Request
  • externalID - string, external identifier which can also be used to retrieve a service request

Response

<response status="ok">
    <serviceRequestID>xxxxxx</serviceRequestID>
</response>
            

Editing a Service Request

URL

https://app.bluefolder.com/api/1.0/serviceRequests/edit.aspx

Request

<request>
   <serviceRequestEdit>
       <serviceRequestID></serviceRequestID>
       <customerID></customerID>
       <customerContactID></customerContactID>
       <customerLocationID></customerLocationID>
       <description></description>
       <statusChange>
           <status></status>
           <commentPrivate></commentPrivate>
           <commentPublic></commentPublic>
           <notifyCustomer></notifyCustomer>
       </statusChange>
       <assignedTo>
           <userID></userID>
           ...
       </assignedTo>
       <billable></billable>
       <category></category>
       <customFields>
           <customField name="field name"></customField>
           ...
       </customFields>
       <dueDate></dueDate>
       <notes></notes>
       <priority></priority>
       <purchaseOrderNo></purchaseOrderNo>
       <referenceNo></referenceNo>
       <serviceManagerID></serviceManagerID>
       <externalID></externalID>
   </serviceRequestEdit>
</request>
            
  • serviceRequestID - (required, if externalID not provided) numeric, must match an existing Service Request in your account
  • customerID - numeric, must match an existing ID from a customer in your customer list
  • customerContactID - numeric, must match an existing contact ID. If not included, the customer's primary contact will be assigned
  • customerLocationID - numeric, must match an existing location ID. If not included, the customer's primary location will be assigned
  • description - string (100 char limit)
  • statusChange - changes the status of the Service Request
    • status - string (50 char limit), the new status
    • commentPrivate - string (no char limit), a comment not visible to your customer
    • commentPublic - string (no char limit), a comment visible to your customer
    • notifyCustomer - boolean, indicates if customer should receive an email notification of the status change
  • assignedTo - designates the userIDs that are to be assigned to the Service Request, will replace any existing assignees
    • userID - numeric, must match an existing User ID in your user list
  • billable - boolean (true/false)
  • category - string (50 char limit)
  • customFields
    • customField - the "name" attribute must specify the exact name of a custom field in your account. The actual value included between the opening and closing "customField" element tags should be a string value, regardless of the custom field's "data type".
  • dueDate - datetime, must be in the format YYYY.MM.DD HH:MM AM
  • notes - string (no char limit)
  • priority - string (50 char limit)
  • purchaseOrderNo - string (25 char limit)
  • referenceNo - string (50 char limit)
  • serviceManagerID - numeric, must match an existing User ID in your user list
  • externalID - (required, if serviceRequestID not provided) string, external identifier which can also be used to retrieve a service request

Response

<response status="ok">
    <serviceRequestID>xxxxxx</serviceRequestID>
    <externalID></externalID>
</response>
            

Retrieving a Single Service Request

URL

https://app.bluefolder.com/api/1.0/serviceRequests/get.aspx

Request

<request>
    <serviceRequestID>xxxxxx</serviceRequestID>
    <externalID></externalID>
</request>
            
  • serviceRequestID - (required, if externalID not provided) numeric, unique service request identifier
  • externalID - (required, if serviceRequestID not provided) unique external identifier

Response

<response status="ok">
    <serviceRequest>
        <serviceRequestID></serviceRequestID>
        <description></description>
        <status></status>
        <customerID></customerID>
        <customerName></customerName>
        <assignedToUserID></assignedToUserID>
        <assignedToUser></assignedToUser>
        <billable></billable>
        <billableTotal></billableTotal>
        <billableExpensesPrice></billableExpensesPrice>
        <billableLaborHours></billableLaborHours>
        <billableLaborPrice></billableLaborPrice>
        <billableMaterialsPrice></billableMaterialsPrice>
        <billToAddressID></billToAddressID>
        <billToAddressName></billToAddressName>
        <billToCity></billToCity>
        <billToCountry></billToCountry>
        <billToID></billToID>
        <billToName></billToName>
        <billToPostalCode></billToPostalCode>
        <billToState></billToState>
        <billToStreetAddress></billToStreetAddress>
        <category></category>
        <closingComments></closingComments>
        <closingReason><closingReason>
        <costExpenses></costExpenses>
        <costLabor></costLabor>
        <costMaterials></costMaterials>
        <costTotal></costTotal>
        <createdByUserID></createdByUserID>
        <customerAction></customerAction>
        <customerContactEmail></customerContactEmail>
        <customerContactID></customerContactID>
        <customerContactName></customerContactName>
        <customerContactPhone></customerContactPhone>
        <customerContactPhoneMobile/>
        <customerLocationCity></customerLocationCity>
        <customerLocationCountry/>
        <customerLocationID></customerLocationID>
        <customerLocationName></customerLocationName>
        <customerLocationNotes/>
        <customerLocationPostalCode></customerLocationPostalCode>
        <customerLocationState></customerLocationState>
        <customerLocationStreetAddress></customerLocationStreetAddress>
        <customerLocationZone></customerLocationZone>
        <dateTimeCreated></dateTimeCreated>
        <dueDate></dueDate>
        <nonBillableExpensesPrice></nonBillableExpensesPrice>
        <nonBillableLaborHours></nonBillableLaborHours>
        <nonBillableLaborPrice></nonBillableLaborPrice>
        <nonBillableMaterialsPrice></nonBillableMaterialsPrice>
        <nonBillableTotal></nonBillableTotal>
        <notes></notes>
        <priority></priority>
        <purchaseOrderNo/>
        <referenceNo/>
        <requestType></requestType>
        <requestDetails></requestDetails>
        <requestVerified></requestVerified>
        <serviceManagerID></serviceManagerID>
        <taxCodeID></taxCodeID>
        <taxRate></taxRate>
        <externalID></externalID>
        <customFields>
            <customField>
                <name></name>
                <value></value>
            </customField>
        </customFields>
        <labor>
            <laborItem>
                <apptID></apptID>
                <billable></billable>
                <billingContractID></billingContractID>
                <billingStatus></billingStatus>
                <createdByUserID></createdByUserID>
                <dateTimeCreated></dateTimeCreated>
                <dateWorked></dateWorked>
                <duration></duration>
                <ID></ID>
                <itemDescription></itemDescription>
                <itemID></itemID>
                <itemIsFlatRate></itemIsFlatRate>
                <itemUnitCost></itemUnitCost>
                <itemUnitListPrice></itemUnitListPrice>
                <itemUnitPrice></itemUnitPrice>
                <notes></notes>
                <notesPrivate></notesPrivate>
                <serviceRequestID></serviceRequestID>
                <startTime></startTime>
                <taskID></taskID>
                <taxable></taxable>
                <totalCost></totalCost>
                <totalPrice></totalPrice>
                <totalPriceBillable></totalPriceBillable>
                <userID></userID>
            </laborItem>
        </labor>
        <materials>
            <materialsItem>
                <apptID></apptID>
                <billable></billable>
                <billingContractID></billingContractID>
                <billingStatus></billingStatus>
                <createdByUserID></createdByUserID>
                <dateTimeCreated></dateTimeCreated>
                <dateUsed></dateUsed>
                <ID></ID>
                <itemDescription></itemDescription>
                <itemID></itemID>
                <itemQuantity></itemQuantity>
                <itemUnitCost></itemUnitCost>
                <itemUnitListPrice></itemUnitListPrice>
                <itemUnitPrice></itemUnitPrice>
                <notes></notes>
                <serviceRequestID></serviceRequestID>
                <taskID></taskID>
                <taxable></taxable>
                <totalCost></totalCost>
                <totalPrice></totalPrice>
                <totalPriceBillable></totalPriceBillable>
            </materialsItem>
        </materials>
        <expenses>
            <expenseItem>
                <apptID></apptID>
                <billable></billable>
                <billingContractID></billingContractID>
                <billingStatus></billingStatus>
                <createdByUserID></createdByUserID>
                <dateTimeCreated></dateTimeCreated>
                <dateUsed></dateUsed>
                <ID></ID>
                <itemDescription></itemDescription>
                <itemID></itemID>
                <itemQuantity></itemQuantity>
                <itemUnitCost></itemUnitCost>
                <itemUnitListPrice></itemUnitListPrice>
                <itemUnitPrice></itemUnitPrice>
                <notes></notes>
                <serviceRequestID></serviceRequestID>
                <taskID></taskID>
                <taxable></taxable>
                <totalCost></totalCost>
                <totalPrice></totalPrice>
                <totalPriceBillable></totalPriceBillable>
                <userID></userID>
            </expenseItem>
        </expenses>
        <log>
            <logEntry>
                <comment_private></comment_private>
                <comment_public></comment_public>
                <createdByUserID></createdByUserID>
                <dateTimeCreated></dateTimeCreated>
                <description></description>
                <entryType></entryType>
                <ID></ID>
                <serviceRequestID></serviceRequestID>
            </logEntry>
        </log>
        <tasks>
            <task>
                <createdByUserID></createdByUserID>
                <dateTimeCreated></dateTimeCreated>
                <displayOrder></displayOrder>
                <serviceRequestID></serviceRequestID>
                <taskDescription/>
                <taskID></taskID>
                <taskName></taskName>
                <taskStatus/>
                <taskType></taskType>
            </task>
        </tasks>
        <equipmentToService>
            <equipmentItem>
                <id></id>
                <equipName></equipName>
                <equipType></equipType>
                <mfrName></mfrName>
                <modelNo></modelNo>
                <serialNo></serialNo>
                <nextServiceDate></nextServiceDate>
                <refNo></refNo>
                <externalID></externalID>
            </equipmentItem>
        </equipmentToService>
    </serviceRequest>
</response>
            

Retrieving a List of Service Requests

URL

https://app.bluefolder.com/api/1.0/serviceRequests/list.aspx

Request

<request>
    <serviceRequestList>
        <listType>basic</listType>
        <customerID>a customer ID to filter by</customerID>
        <customerName exactMatch="true|false">a customer name to filter by</customerName>
        <dateRange dateField="dateTimeCreated|dateTimeClosed">
            <startDate>MM-DD-YYYY HH:MM AM/PM</startDate>
            <endDate>MM-DD-YYYY HH:MM AM/PM</endDate>
        </dateRange>
        <status>a status value to filter by</status>
        <billingStatus>a billing status value to filter by</billingStatus>
        <invoiceNo>an invoice number to search for</invoiceNo>
        <referenceNo>a reference number to search for</referenceNo>
    </serviceRequestList>
</request>
            
  • listType - string, either 'basic' or 'full'
  • customerID - string, filters the list by customerID
  • customerName - string, filters the list by the 'Customer Name'
  • dateRange - filters the list by the specified date field (either 'dateTimeCreated' or 'dateTimeClosed').
  • status - string, filters the list by 'Status' (use 'open' to retrieve all non-closed Service Requests)
  • billingStatus - string, filters the list by the 'Billing Status' field
  • invoiceNo- string, filters the list by the 'Invoice No.' field
  • referenceNo - string, filters the list by the 'Reference No.'

Response (for 'basic' list)

<response status="ok">
    <serviceRequestList>
        <serviceRequest>
            <serviceRequestID></serviceRequestID>
            <description></description>
            <status></status>
            <category></category>
            <priority></priority>
            <assignedToUserID></assignedToUserID>
            <assignedToUser></assignedToUser>
            <customerID></customerID>
            <customerName></customerName>
            <customerContactEmail></customerContactEmail>
            <customerContactID></customerContactID>
            <customerContactName></customerContactName>
            <customerContactPhone></customerContactPhone>
            <customerContactPhoneMobile></customerContactPhoneMobile>
            <customerLocationCity></customerLocationCity>
            <customerLocationCountry></customerLocationCountry>
            <customerLocationID></customerLocationID>
            <customerLocationName></customerLocationName>
            <customerLocationNotes></customerLocationNotes>
            <customerLocationPostalCode></customerLocationPostalCode>
            <customerLocationState></customerLocationState>
            <customerLocationStreetAddress></customerLocationStreetAddress>
            <customerLocationZone></customerLocationZone>
            <dateTimeCreated></dateTimeCreated>
            <dueDate></dueDate>
            <dateTimeClosed></dateTimeClosed>
            <serviceManagerID></serviceManagerID>
            <serviceManager></serviceManager>
            <externalID></externalID>
        </serviceRequest>
        <serviceRequest>
            ...
        </serviceRequest>
    </serviceRequestList>
</response>
            

Retrieving Service Request Files, Links, and Signatures

URL

https://app.bluefolder.com/api/1.0/serviceRequests/getFiles.aspx

Request

<request>
    <serviceRequestID>xxxxxx</serviceRequestID>
</request> 

Response

<response status='ok'>
    <serviceRequestFile>
        <serviceRequestFileID></serviceRequestFileID>
        <serviceRequestSignedDocumentID>
        </serviceRequestSignedDocumentID>
        <isexternal></isexternal>
        <issigneddocument></issigneddocument>
        <fileDescription></fileDescription>
        <fileLastModified></fileLastModified>
        <fileName></fileName>
        <fileSize></fileSize>
        <fileType></fileType>
        <private></private>
        <postedOn></postedOn>
        <postedBy></postedBy>
        <fileURL></fileURL>
        <documentName></documentName>
        <signatureFilePath_Customer>
        </signatureFilePath_Customer>
        <signatureFilePath_Technician>
        </signatureFilePath_Technician>
        <signatureName_Customer></signatureName_Customer>
        <signatureName_Technician></signatureName_Technician>
    </serviceRequestFile>
</response>
        
  • serviceRequestFileID - integer, unique ID for the service request file or link(0 for all signature files)
  • serviceRequestSignedDocumentID - integer, unique ID for the signed document (0 for all service request files and links)
  • isexternal - boolean, true for external links, false for files and signatures
  • issigneddocument - boolen, true for all signed document entries (false for service request files and links)
  • fileDescription - string, description tag for the file, link, or signature
  • fileLastModified - string date, last modification date and time
  • fileName - string, name of the file (may be URL for the link, name of a physical file, or blank)
  • fileSize - integer, size of the file (0 for links and signature documents)
  • fileType - string, type of file (image/jpeg, external, signature, etc.)
  • private - boolen, true if the file or link will not appear on any customer portal
  • postedOn - string date, when the file, link, or signature file was posted to BlueFolder
  • fileURL - string, value of the link to a file or link (blank for signature documents)
  • documentName - string, name of the document (may be blank)
  • signatureFilePath_Customer - string, complete URL to the customer's signature capture image
  • signatureFilePath_Technician - string, complete URL to the technician's signature capture image
  • signatureName_Customer - string, printed name for the customer
  • signatureName_Technician - string, printed name for the technician


Retrieving History List for Single Service Request

URL

https://app.bluefolder.com/api/1.0/serviceRequests/getHistory.aspx

Request

<request>
    <serviceRequestID>xxxxxx</serviceRequestID>
    <externalID></externalID>
</request>
            
  • serviceRequestID - (required, if externalID not provided) numeric, unique service request identifier
  • externalID - (required, if serviceRequestID not provided) unique external identifier

Response

<response status='ok'>
    <serviceRequestHistoryList>
        <serviceRequestHistory>
            <ID></ID>
            <serviceRequestID></serviceRequestID>
            <commentPrivate></commentPrivate>
            <commentPublic></commentPublic>
            <description></description>
            <entryDate></entryDate>
            <entryType></entryType>
            <private></private>
            <userId></userId>
            <userName></userName>
        </serviceRequestHistory>
    </serviceRequestHistoryList>
</response>
        
  • ID - numeric, unique ID for the service request comment
  • serviceRequestID - numeric, unique ID for the service request
  • commentPrivate - string, private comment, if the entry is a user comment
  • commentPublic - string public comment, if the entry is a user comment
  • description - string, description of the history entry
  • entryDate - date, when the history entry was created
  • entryType - string, the type of entry (comment, edit, close, etc.)
  • private - boolean, specifying whether the history entry is visible to customers
  • userId - integer, unique identifier for the username (if available)
  • userName - string, full name of the user who created the entry (if available)
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request