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 - filters the list by the specified date field (either 'dateTimeCreated' or 'dateTimeClosed').
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.'

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>
</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 - 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>