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, indicates if customer should receive an email notification for this action
  • 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, indicates if customer should receive an email notification for this action
  • 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