Logo
Submit a request

Service Requests (API)

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>
       <linkedToServiceRequestId></linkedToServiceRequestId>
       <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 - numeric, if provided the value 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
    • equipmentId - 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)
  • linkedToServiceRequestId - numeric, must match a Service Request Id from a Service Request in your account
  • 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>
       <linkedToServiceRequestId></linkedToServiceRequestId>
       <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)
  • linkedToServiceRequestId - numeric, must match a Service Request Id from a Service Request in your account
  • 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>
        <linkedToServiceRequestId></linkedToServiceRequestId>
        <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>
        <equipmentId>an equipmentId to filter by</equipmentId>
        <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 - (required, 180 day range by default) filters the list by the specified date field (either 'dateTimeCreated' or 'dateTimeClosed'). The range cannot span more than 180 days; a wider range returns a validation error rather than a partial or truncated result.
  • equipmentId - GUID, which is the unique Id for the equipment item to filter by
  • 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.'

Note: if the request omits a dateRange, the list is not unbounded. It defaults to Service Requests with a 'dateTimeCreated' within the last 180 days, rather than the complete history. Whichever date range actually applied to a given call, explicit or defaulted, is always echoed back in the response's <filtersApplied> node described below.

Response (for 'basic' list)

<response status="ok">
    <serviceRequestList>
        <serviceRequest>
            <accountManagerId></accountManagerId>
            <billable></billable>
            <billableTotal></billableTotal>
            <billingStatus></billingStatus>
            <costTotal></costTotal>
            <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>
    <filtersApplied>
        <customerId>a customerId to filter by</customerId>
        <customerName exactMatch="true|false">a customer name to filter by</customerName>
        <equipmentId>an equipmentId to filter by</equipmentId>
        <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>
        <dateRange dateField="dateTimeCreated|dateTimeClosed" wasDefaulted="true|false">
            <startDate>MM-DD-YYYY HH:MM AM/PM</startDate>
            <endDate>MM-DD-YYYY HH:MM AM/PM</endDate>
        </dateRange>
    </filtersApplied>
</response>
  • filtersApplied - echoes back the filter criteria actually used to produce this list, in the same shape used to submit them in the request. Only the criteria actually in effect are included. For example, customerId only appears if one was supplied. dateRange is always included, since a date filter is always in effect: either the one supplied in the request, or the default described above.
  • dateRange's wasDefaulted attribute is 'true' when no dateRange was supplied in the request and the default 180-day window was applied instead, or 'false' when the dateRange came directly from the request.

Note: for very large result sets, the response may be streamed rather than returned all at once. When this happens, the root <response> element includes a streamed="true" attribute (status remains "ok"), and a <result> element is appended as the last child of <response> once the list has finished sending, with status "ok" if it completed successfully, or "fail" with error details if it did not. Most responses are well under the size where this applies and will never include either of these.

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 - boolean, 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>

Deleting a Service Request

URL

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

Request

<request>
    <serviceRequestDelete>
        <serviceRequestId>xxxxxx</serviceRequestId>
    </serviceRequestDelete>
</request>
  • serviceRequestId - (required) numeric, must match an existing Service Request in your account

Response

<?xml version="1.0" ?>
<response status='ok'>
    <serviceRequestId></serviceRequestId>
</response>
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request