Logo
Submit a request
Follow

Service Requests

Adding a Service Request

URL

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

Request

<request>
   <serviceRequestAdd>
       <accountManagerId></accountManagerId>
       <billable></billable>
       <customerId></customerId>
       <customerContactId></customerContactId>
       <customerLocationId></customerLocationId>
       <customFields>
           <customField name="field name"></customField>
           ...
       </customFields>
       <description></description>
       <detailedDescription></detailedDescription>
       <dueDate></dueDate>
       <equipmentToService>
           <equipmentId></equipmentId>
           ...
       </equipmentToService>
       <externalId></externalId>
       <notifyCustomer></notifyCustomer>
       <priority></priority>
       <purchaseOrderNo></purchaseOrderNo>
       <referenceNo></referenceNo>
       <serviceManagerId></serviceManagerId>
       <sourceName></sourceName>
       <sourceId></sourceId>
       <status></status>
       <taxCodeId></taxCodeId>
       <type></type>
   </serviceRequestAdd>
</request>
            
  • accountManagerId - numeric, must match an existing User Id in your user list
  • billable - boolean (true/false)
  • 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
  • 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".
  • description - (required) string (100 char limit)
  • detailedDescription - string (no char limit)
  • dueDate - datetime, must be in the format YYYY.MM.DD HH:MM AM
  • 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
  • externalId - string, external identifier which can also be used to retrieve a service request (externalId must be a unique value)
  • notifyCustomer - boolean (true/false), indicates if customer should receive an email notification for this action. The value defaults to the preferences that are set for the customer as specified in Customer Notifications. This value is ignored if the company does not allow notification preferences to be overriden or if the user does not have permission to override customer notifications.
  • 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
  • sourceName - string (50 char limit), the name of the external system that originated the Service Request
  • sourceId - string (50 char limit), an identifier that refers to an item in the external system that originated the Service Request
  • status - string (50 char limit)
  • taxCodeId = numeric, must match an existing taxCode Id. If not included, the default tax code will be used.
  • type - string (50 char limit)

Response

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

Editing a Service Request

URL

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

Request

<request>
   <serviceRequestEdit>
       <accountManagerId></accountManagerId>
       <billable></billable>
       <customerId></customerId>
       <customerContactId></customerContactId>
       <customerLocationId></customerLocationId>
       <customFields>
           <customField name="field name"></customField>
           ...
       </customFields>
       <description></description>
       <detailedDescription></detailedDescription>
       <externalId></externalId>
       <dueDate></dueDate>
       <notifyCustomer></notifyCustomer>
       <priority></priority>
       <purchaseOrderNo></purchaseOrderNo>
       <referenceNo></referenceNo>
       <serviceManagerId></serviceManagerId>
       <serviceRequestId></serviceRequestId>
       <statusChange>
           <status></status>
           <comment></comment>
           <commentIsPublic></commentIsPublic>
       </statusChange>
       <taxCodeId></taxCodeId>
       <type></type>
   </serviceRequestEdit>
</request>
            
  • accountManagerId - numeric, must match an existing User Id in your user list
  • billable - boolean (true/false)
  • 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
  • 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".
  • description - string (100 char limit)
  • detailedDescription - string (no char limit)
  • dueDate - datetime, must be in the format YYYY.MM.DD HH:MM AM
  • externalId - (required, if serviceRequestId not provided) string, external identifier which can also be used to retrieve a service request (externalId must be a unique value)
  • notifyCustomer - boolean (true/false), indicates if customer should receive an email notification for this action. The value defaults to the preferences that are set for the customer as specified in Customer Notifications. This value is ignored if the company does not allow notification preferences to be overriden or if the user does not have permission to override customer notifications.
  • 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
  • serviceRequestId - (required, if externalId not provided) numeric, must match an existing Service Request in your account
  • statusChange - changes the status of the Service Request
    • status - string (50 char limit), the new status
    • comment - string (no char limit), a comment related to the status change
    • commentIsPublic - boolean (true/false), indicates if comment should be public (visible to your customer)
  • taxCodeId = numeric, must match an existing taxCode Id. To clear the existing tax code for a Service Request, pass in a taxCodeId of 0.
  • type - string (50 char limit)

Response

<response status="ok">
    <serviceRequestId>xxxxxx</serviceRequestId>
    <externalId></externalId>
</response>
            

Retrieving a Single Service Request

URL

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

Request

<request>
    <serviceRequestId>xxxxxx</serviceRequestId>
    <externalId></externalId>
    <groupItemsByType></groupItemsByType>
</request>
            
  • serviceRequestId - (required, if externalId not provided) numeric, unique service request identifier
  • externalId - (required, if serviceRequestId not provided) unique external identifier
  • groupItemsByType - (optional) boolean, indicates if items should be grouped by item type in the response (true by default)

Response

<response status="ok">
    <serviceRequest>
        <accountManagerId></accountManagerId>
        <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>
        <costExpenses></costExpenses>
        <costLabor></costLabor>
        <costMaterials></costMaterials>
        <costTotal></costTotal>
        <createdByUserId></createdByUserId>
        <customerAction></customerAction>
        <customerContactEmail></customerContactEmail>
        <customerContactId></customerContactId>
        <customerContactName></customerContactName>
        <customerContactPhone></customerContactPhone>
        <customerContactPhoneMobile></customerContactPhoneMobile>
        <customerId></customerId>
        <customerLocationCity></customerLocationCity>
        <customerLocationCountry></customerLocationCountry>
        <customerLocationId></customerLocationId>
        <customerLocationName></customerLocationName>
        <customerLocationNotes/>
        <customerLocationPostalCode></customerLocationPostalCode>
        <customerLocationState></customerLocationState>
        <customerLocationStreetAddress></customerLocationStreetAddress>
        <customerLocationZone></customerLocationZone>
        <customerName></customerName>
        <dateTimeCreated></dateTimeCreated>
        <dateTimeClosed></dateTimeClosed>
        <dateTimeExportedForBilling></dateTimeExportedForBilling>
        <description></description>
        <detailedDescription></detailedDescription>
        <dueDate></dueDate>
        <externalId></externalId>
        <nonBillableExpensesPrice></nonBillableExpensesPrice>
        <nonBillableLaborHours></nonBillableLaborHours>
        <nonBillableLaborPrice></nonBillableLaborPrice>
        <nonBillableMaterialsPrice></nonBillableMaterialsPrice>
        <nonBillableTotal></nonBillableTotal>
        <priority></priority>
        <purchaseOrderNo></purchaseOrderNo>
        <referenceNo></referenceNo>
        <requestDetails></requestDetails>
        <requestVerified></requestVerified>
        <serviceContractId></serviceContractId>
        <serviceManagerId></serviceManagerId>
        <serviceRequestId></serviceRequestId>
        <sourceName></sourceName>
        <sourceId></sourceId>
        <sourceType></sourceType>
        <status></status>
        <statusLastUpdated></statusLastUpdated>
        <statusAge_hours></statusAge_hours>
        <taxCodeId></taxCodeId>
        <taxRate></taxRate>
        <type></type>
        <assignments>
            <assignment>
                <assignmentId></assignmentId>
                <assigneeUserIds></assigneeUserIds>
                <type></type>
                <startDate></startDate>
                <endDate></endDate>
                <allDayEvent></allDayEvent>
                <assignmentComment></assignmentComment>
                <dateTimeCreated></dateTimeCreated>
                <createdByUserId></createdByUserId>
                <isComplete></isComplete>
                <dateTimeCompleted></dateTimeCompleted>
                <completedByUserId></completedByUserId>
            </assignment>
        </assignments>
        <customFields>
            <customField>
                <name></name>
                <value></value>
            </customField>
        </customFields>
        <labor>
            <laborItem>
                <apptId></apptId>
                <billable></billable>
                <billingContractId></billingContractId>
                <billingStatus></billingStatus>
                <comment></comment>
                <commentIsPublic></commentIsPublic>
                <createdByUserId></createdByUserId>
                <dateTimeCreated></dateTimeCreated>
                <dateWorked></dateWorked>
                <duration></duration>
                <id></id>
                <itemDescription></itemDescription>
                <itemId></itemId>
                <itemIsFlatRate></itemIsFlatRate>
                <itemUnitCost></itemUnitCost>
                <itemUnitListPrice></itemUnitListPrice>
                <itemUnitPrice></itemUnitPrice>
                <serviceRequestId></serviceRequestId>
                <startTime></startTime>
                <taxable></taxable>
                <totalCost></totalCost>
                <totalPrice></totalPrice>
                <totalPriceBillable></totalPriceBillable>
                <userId></userId>
            </laborItem>
        </labor>
        <materials>
            <materialsItem>
                <apptId></apptId>
                <billable></billable>
                <billingContractId></billingContractId>
                <billingStatus></billingStatus>
                <comment></comment>
                <commentIsPublic></commentIsPublic>
                <createdByUserId></createdByUserId>
                <dateTimeCreated></dateTimeCreated>
                <dateUsed></dateUsed>
                <id></id>
                <itemDescription></itemDescription>
                <itemId></itemId>
                <itemQuantity></itemQuantity>
                <itemUnitCost></itemUnitCost>
                <itemUnitListPrice></itemUnitListPrice>
                <itemUnitPrice></itemUnitPrice>
                <serviceRequestId></serviceRequestId>
                <taxable></taxable>
                <totalCost></totalCost>
                <totalPrice></totalPrice>
                <totalPriceBillable></totalPriceBillable>
            </materialsItem>
        </materials>
        <expenses>
            <expenseItem>
                <apptId></apptId>
                <billable></billable>
                <billingContractId></billingContractId>
                <billingStatus></billingStatus>
                <comment></comment>
                <commentIsPublic></commentIsPublic>
                <createdByUserId></createdByUserId>
                <dateTimeCreated></dateTimeCreated>
                <dateUsed></dateUsed>
                <id></id>
                <itemDescription></itemDescription>
                <itemId></itemId>
                <itemQuantity></itemQuantity>
                <itemUnitCost></itemUnitCost>
                <itemUnitListPrice></itemUnitListPrice>
                <itemUnitPrice></itemUnitPrice>
                <serviceRequestId></serviceRequestId>
                <taxable></taxable>
                <totalCost></totalCost>
                <totalPrice></totalPrice>
                <totalPriceBillable></totalPriceBillable>
                <userId></userId>
            </expenseItem>
        </expenses>
        <log>
            <logEntry>
                <comment></comment>
                <commentIsPublic></commentIsPublic>
                <createdByUserId></createdByUserId>
                <dateTimeCreated></dateTimeCreated>
                <description></description>
                <entryType></entryType>
                <id></id>
                <serviceRequestId></serviceRequestId>
            </logEntry>
        </log>
        <equipmentToService>
            <equipmentItem>
                <equipmentId></equipmentId>
                <equipName></equipName>
                <equipType></equipType>
                <externalId></externalId>
                <mfrName></mfrName>
                <modelNo></modelNo>
                <serialNo></serialNo>
                <nextServiceDate></nextServiceDate>
                <refNo></refNo>
            </equipmentItem>
        </equipmentToService>
    </serviceRequest>
</response>
            

Retrieving a List of Service Requests

URL

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

Request

<request>
    <serviceRequestList>
        <listType>basic</listType>
        <customerId>a customerId 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>
            <accountManagerId></accountManagerId>
            <billable></billable>
            <billableTotal></billableTotal>
            <billingStatus></billingStatus>
            <customerContactEmail></customerContactEmail>
            <customerContactId></customerContactId>
            <customerContactName></customerContactName>
            <customerContactPhone></customerContactPhone>
            <customerContactPhoneMobile></customerContactPhoneMobile>
            <customerId></customerId>
            <customerLocationCity></customerLocationCity>
            <customerLocationCountry></customerLocationCountry>
            <customerLocationId></customerLocationId>
            <customerLocationName></customerLocationName>
            <customerLocationNotes></customerLocationNotes>
            <customerLocationPostalCode></customerLocationPostalCode>
            <customerLocationState></customerLocationState>
            <customerLocationStreetAddress></customerLocationStreetAddress>
            <customerLocationZone></customerLocationZone>
            <customerName></customerName>
            <dateTimeCreated></dateTimeCreated>
            <dateTimeClosed></dateTimeClosed>
            <description></description>
            <detailedDescription></detailedDescription>
            <dueDate></dueDate>
            <externalId></externalId>
            <priority></priority>
            <priorityLabel></priorityLabel>
            <serviceManagerId></serviceManagerId>
            <serviceRequestId></serviceRequestId>
            <status></status>
            <timeOpen_hours></timeOpen_hours>
            <type></type>
        </serviceRequest>
        <serviceRequest>
            ...
        </serviceRequest>
    </serviceRequestList>
</response>
            

Retrieving Service Request Files, Links, and Signed Documents

URL

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

Request

<request>
    <serviceRequestId>xxxxxx</serviceRequestId>
</request> 

Response

<response status='ok'>
    <serviceRequestFile>
        <serviceRequestFileId></serviceRequestFileId>
        <serviceRequestSignedDocumentId></serviceRequestSignedDocumentId>
        <isExternalLink></isExternalLink>
        <isSignedDocument></isSignedDocument>
        <fileDescription></fileDescription>
        <fileLastModified></fileLastModified>
        <fileName></fileName>
        <fileSize></fileSize>
        <fileType></fileType>
        <private></private>
        <postedOn></postedOn>
        <postedBy></postedBy>
        <linkUrl></linkUrl>
        <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 file or link (0 for signed documents)
  • serviceRequestSignedDocumentId - integer, unique id for the signed document (0 for all files and links)
  • isExternalLink - boolean, true for external links, false for files and signed documents
  • isSignedDocument - boolean, true for all signed document entries (false for files and links)
  • fileDescription - string, description tag for the file, link, or signed document
  • 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 signed documents)
  • fileType - string, type of file (e.g. 'image/jpeg', 'external', 'signedDocument', etc.)
  • private - boolen, true if the file or link will not appear on the customer portal
  • postedOn - string date, when the file, link, or signed document was posted
  • linkUrl - string, value of the link to a file or link (blank for signed documents)
  • documentName - string, name of the document (may be blank)
  • signatureFilePath_Customer - string, complete URL to the image of the customer's signature
  • signatureFilePath_Technician - string, complete URL to the image of the technician's signature
  • 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/2.0/serviceRequests/getHistory.aspx

Request

<request>
    <serviceRequestId>xxxxxx</serviceRequestId>
    <externalId></externalId>
</request>
            
  • serviceRequestId - (required, if externalId not provided) numeric, unique service request id
  • externalId - (required, if serviceRequestId not provided) unique external id

Response

<response status='ok'>
    <serviceRequestHistoryList>
        <serviceRequestHistory>
            <id></id>
            <serviceRequestId></serviceRequestId>
            <comment></comment>
            <commentIsPublic></commentIsPublic>
            <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
  • comment - string, the comment text
  • commentIsPublic - boolean, indicates if comment is public (visible to customers)
  • 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)

Retrieving Custom Field List for Service Requests

URL

https://app.bluefolder.com/api/2.0/serviceRequests/getCustomFields.aspx

Request

<request></request>
            
 

Response

<response status="ok">
    <customFields>
        <customField>
            <DisplayOrder></DisplayOrder>
            <FieldDataType></FieldDataType>
            <FieldId></FieldId>
            <FieldListValues>
                <FieldListValue></FieldListValue>
                ...
            </FieldListValues>
            <FieldName></FieldName>
            <FieldRequired></FieldRequired>
        </customField>
        ...
    </customFields>
</response>
            
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request