Generally speaking API docs are a laundry listing of APIs. And while those APIs are described, the consumer of those APIs generally needs to figure out how to go about stringing together the various APIs in order to accomplish the desired result. Our objective is not only to list the available Dispatch APIs that you have at your disposal, but also to provide you with step by step guidance for the common use cases that we generally encounter. And for that reason we refer to this document as our API \"playbook\" rather than API \"docs\".
\n","_postman_id":"e571f45f-9123-4192-ab13-30897a81b0b8"},{"name":"How this document is organized","item":[],"id":"89b5e058-bddc-45b9-a7f9-24768630b499","description":"Quick Starts
\nThe Quick Starts cover the most common use cases that are typically required in building an integration with the Dispatch Platform. The recommendation is to follow the Quick Start section that is relevant to your use case which should allow you to quickly stand up a bi-directional integration with Dispatch. Our experience is that the Quick Starts are usually all that is necessary to build a comprehensive, production-ready integration with the Dispatch Platform. You should pick the Quick Start that is relevant to your use case:
\nUse Cases
\nThe Use Cases includes guidance for how to go about building an integration for a variety of different use cases as the need may arise over time or based on your specific needs.
\n\"To Dispatch\" and \"From Dispatch\"
\nEach section is sub-divided into \"To Dispatch\" and \"From Dispatch\" sections to make it clear in which direction the information is flowing.
\n","_postman_id":"89b5e058-bddc-45b9-a7f9-24768630b499"},{"name":"High Level Flow & Code Samples","item":[],"id":"51ed9805-c1ff-4956-a976-424d100d0beb","description":"Please view the working code samples for connecting to our inbound and outbound endpoints. This is a valuable resource that will provide you with a jump start on working with Dispatch Connect (or henceforth \"The Connector\").
\nThe following diagram shows a high level interaction with the connector endpoints:
\n![](\"https://user-images.githubusercontent.com/8817368/39719546-38dab446-5242-11e8-9094-941cb1672a8f.png\")
\n\nOur goal is to make connecting with Dispatch simple. To this end, we don't encumber you with multiple different endpoints to hit depending on what you're trying to do. Rather, all inbound requests are sent to a single endpoint (as illustrated above). Similarly outbound updates are retrieved from a single endpoint.
\nThat said, we are of course here to help you with any questions that you might have. And it's of course possible that we haven't covered every angle. If we encounter such a case, we will endeavor to make those updates to this documentation rather than address them in scattered emails and what not. In this sense, this is a living repository which will be updated as necessary to incorporate tweaks and enhancements as they become relevant and/or necessary.
\n","_postman_id":"51ed9805-c1ff-4956-a976-424d100d0beb"},{"name":"General Conventions","item":[],"id":"2f62cae6-7c1e-4eb5-827b-0e761068ad07","description":"All date fields send to Dispatch should be an ISO timestamp unless expressly stated otherwise
\nAddresses:
\ncountry is defaulted to United States. The only other valid value at the moment is Canada. Or you can leave this out altogether and we'll assume it refers to the good ol' US of A.state accepts the 2 character acronym or the correctly spelled long name (M i s s i s i s s i p p i !)External ID - This correlates to the Enterprise ID or the identifier from an external system where the job was originated. We use this for match purposes on the Dispatch side and therefore there is no need for you to store the Dispatch IDs in your system. The convention for external IDs on a payload is as follows:
\nexternal_id - this is the external ID for the object itself. For example, if you're passing in a \"job\" record type, this will be your unique reference for the job record.external_related_id - this is the external ID that points to a related object. For example (assuming a \"job\" record type):external_organization_id - this is the job's external organization unique referenceexternal_customer_id - this is the job's external customer unique reference[\n {\n \"header\": {\n \"record_type\": \"job\",\n ...\n },\n \"record\": {\n \"external_id\": \"your_job_external_id\",\n \"external_organization_id\": \"your_job's_organization_external_id\",\n \"external_customer_id\": \"your_job's_customer_external_id\",\n ...\n }\n }\n]\n\nThis is used throughout these docs is the only authentication that you should be using other than certainly particular use cases pointed out in this doc and described next.
\nDispatch will provision you keys that will look something like this:
\nAnd you will pass them into the API headers as described here and the code samples.
\nAPI calls made by this method are asynchronous and therefore you will always get a 200 OK response for a successful POST. If you are curious as to why this is the case, please see the first question in the FAQ.
If you want to associate the corresponding Dispatch IDs from a successful operation or be notified of errors you will need to subscribe to theack and error messages.
Our oauth authentication method is only for used for APIs that need to work synchronously and those examples are called out explicitly in these docs. Chances are that you will never need to use this method of authentication, so you can skip this section and come back to it if and when it becomes necessary.
\nDispatch will provision you keys that will look something like this:
\nThis will return an access_token that you will need to pass intoAuthorization key of the request header for all subsequent API calls:
Authorization: Bearer xxxx30eaf43d7bf8f27df23a717a0033026a18c62d2a34e64450b528e1726a75\n\nThere are 2 types of authentication used for integration to Dispatch.
\nThe recommended steps to get started are as follows:
\nReceive auth keys from Dispatch
\nUse the working code samples to start authenticating and sending/receiving data (see next step)
\nYou should now be able to log into https://work-sandbox.dispatch.me using the service provider phone number that you supplied in your payload and “work the job” as a dispatcher and a tech. It’s a very intuitive experience but please see our training for additional help (the training directs you to go to our production apps but during testing you’ll be using our sandbox apps)
\nDetermine which \"Quick Start\" best fits your integration model
\nWire up your system to send data to Dispatch. The payload structure should either be in an agreed upon custom format or in the canonical formats described in the “To Dispatch” playbook section.
\nWire up your system to receive updates from Dispatch. The updates you make will be sent to our agent/out endpoint waiting for you to pick them up and process them. The “From Dispatch” playbook section describes the updates you can expect to receive (If you do not “care” for some of these updates we’d recommend just acknowledging and ignoring them. At some point when you do care for them you can just start consuming them). The payload structure will either be in the canonical formats described in the above link (default) or in an agreed upon custom format.
Testing and cutover
\nPlease let us know if you have any questions
\n","_postman_id":"1637f979-c83d-4e30-ac95-c8cd638300bf"},{"name":"Dispatch Inbound (+)","item":[{"name":"Payload Structure","item":[],"id":"6e0e06aa-e37c-4715-96a2-bb0d3bcfc1ea","description":"If required, you can send data in literally any format to Dispatch. If you do that, then it will be necessary to map from the structure that you are sending through to a structure that Dispatch understands. This exercise is typically performed by a member of the Dispatch ProServices team.
\nIt is possible however to eliminate this mapping step using our canonical payloads. The payload examples included within this document follow Dispatch's \"canonical\" payload. If you adhere to these, the connector will know how to process them automatically. If you are sending custom payloads, then you do not need to be adhering to these canonical structures.
\nIn a nutshell:
\nThe endpoint to send all inbound requests are:
\nOur inbound sample code has some working examples for both canonical and customer payloads in a number of different programming languages. This should help you get going.
\nTo be clear: Dispatch only has a single endpoint with which to send all inbound requests. Each record identifies what transaction needs to run by inspecting:
\nRecordType http header or ...The following should be included in the http headers:
\nX-Dispatch-Key - e.g. account|999|acme - public IDX-Dispatch-Signature - the hmac hash of the private keyRecordType - (optional - see section above) e.g. \"job\", \"organization\" - can be any value that distinguishes the payload. This is only required if the the payload content cannot be used to determine what record type is being passed.MessageId - (optional but recommended) this should be a unique value for the message being sent. You can use this to correlate with the \"msg_id\" that is sent with the ack and err outbound messagesThe external_id you pass in is used for lookup logic. Such that:
external_id does not exist on Dispatch, a new record will be insertedLet’s say you want to create job, creating an appointment and assign it to a technician and add note all in one go. You can simply pass all this into the payload and call the API once. The Quick Starts are good examples that employ this option
\nTake note that the order is important as the payload will be processed in the order the data is provided.
\nSo essentially, you want to have the following sections passed into the payload:
\nThe payload illustrates how you can send over multiple requests at once.
\nIn the event this is relevant, we recommend you reach out to your Dispatch representative to advise on the payload structure to send.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"5e03f259-b9d3-45f4-98c8-905d5af3f1f1"},{"name":"Bulk Processing","id":"02e5fd93-cf79-4a4e-8378-f1878ea71015","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\r\n {\r\n \"header\": {\r\n \"record_type\": \"job\",\r\n \"version\": \"v3\"\r\n },\r\n \"record\": {\r\n \"title\": \"job 1\",\r\n \"other payload fields\": \"...\"\r\n }\r\n },\r\n {\r\n \"header\": {\r\n \"record_type\": \"job\",\r\n \"version\": \"v3\"\r\n },\r\n \"record\": {\r\n \"title\": \"job 2\",\r\n \"other payload fields\": \"...\"\r\n }\r\n },\r\n {\r\n \"header\": {\r\n \"record_type\": \"job\",\r\n \"version\": \"v3\"\r\n },\r\n \"record\": {\r\n \"title\": \"job 3\",\r\n \"other payload fields\": \"...\"\r\n }\r\n },\r\n {\r\n \"header\": {\r\n \"record_type\": \"job\",\r\n \"version\": \"v3\"\r\n },\r\n \"record\": {\r\n \"title\": \"job 4\",\r\n \"other payload fields\": \"and so on\"\r\n }\r\n }\r\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Send a whole bunch of requests through at once. The connector will take care of the rest. The payload illustrates how you can send over multiple requests at once.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"02e5fd93-cf79-4a4e-8378-f1878ea71015"}],"id":"c7dc4f42-670e-4e0c-b778-7c8444a1fff7","description":"You'll notice that all the canonical payload examples are sent in an array structure i.e. it is enclosed in []. This means that you can send your requests individually or in bulk. It is generally recommended to send as many requests at a time. So if for example you are polling your data and picking up a change set to send over to Dispatch, you can either:
It is generally recommended to follow the latter approach where ever possible.
\nThis section illustrates two common use cases for bulk processing.
\nWe are just providing the canonical example for the organization record. As you'll notice the headers of the file have a dot notation that correlates with the corresponding canonical json format. The same is true for the import/export CSV format for the other Dispatch entities (technician, job, appointment, billing documents etc.).
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"57375c97-8b93-4368-9ada-571e30440689"}],"id":"6a263b72-80a6-48d0-b9b2-13c323befbbd","description":"The connector can support any inbound and outbound format. However as CSV is a fairly common format we have added a section to address individually. And... as with all connector integrations - we can work with CSV files with any column header naming convention (we have a simple translation layer that can be configured to transform the input into the format required for importing to Dispatch). And similarly for the outbound - if the file needs to have particular column headers we can do the translation on our end to meet that objective.
\nThat notwithstanding, the rest of this section will use the Dispatch inbound/outbound canonical format to illustrate.
\n","event":[{"listen":"prerequest","script":{"id":"db40bbef-dd4d-49b8-8a3e-db398c10fe62","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"06dc852b-face-441c-afd8-c061ee30e178","type":"text/javascript","exec":[""]}}],"_postman_id":"6a263b72-80a6-48d0-b9b2-13c323befbbd"}],"id":"586587ee-ec31-4347-90d7-52df30436b3b","description":"At it's heart, the connector is an orchestrator of Dispatch's lower level APIs. A single update to Dispatch may involve multiple lower level interactions (GET, POST, PATCH on jobs, customers, etc.). We don't want you to have to be encumbered with having to know how to interact with Dispatch's lower level APIs. Rather our expectation is that you send all the data needed for a given transaction in a single payload to a single endpoint and the connector will perform all the magic for you.
\n","_postman_id":"586587ee-ec31-4347-90d7-52df30436b3b"}],"id":"8cfef1f4-fd46-49cc-91c3-7d63dee4a392","description":"The To Dispatch sections in this document describe the Dispatch Inbound integration use cases.
\n","_postman_id":"8cfef1f4-fd46-49cc-91c3-7d63dee4a392"},{"name":"Dispatch Outbound (+)","item":[{"name":"Payload Structure","item":[],"id":"3571ed91-9317-4784-a706-b7721daed3db","description":"Every payload that you pick up from the outbound endpoint will include the following payload wrapper. The details inside the Payload key will contain the relevant updates for your system. The wrapper elements - specifically ProcedureIDand Receipt are used to mark the payload as having been received and will remove the payload from the queue. The technical steps for doing so are best illustrated in the outbound code samples.
[\n {\n \"Message\": {\n \"Request\": {\n \"ProcedureID\": \"b332b621-f7ef-405d-8075-7332aef9bba7\",\n \"Type\": \"some_type\",\n \"Payload\": {\n \"some_payload\": \"either the canonical described in this document or an agreed upon custom format\"\n }\n },\n \"ID\": \"ed172c8b-aba0-4f1b-b477-6dc9c487fcbd\",\n \"Receipt\": \"AQEBQ4Uw8YrVICgfZjXqtQhK6/PBodouACu8J4P0z27ysnHLTi7rC0r7cueMFnq9CuDpG6lXtCTKdXrjjrUM0GTi3PCY/tjCAd8uC77KN3tTLGFwiSKRUHoni4wLqRjyvNYnJFv2Y1sHn8DSgSIzB8kx5Zv6krK17jvzwhxom0+nM5g99iuavW+TtrDdnQVwc5lPw5/q+AuxSVzkWQS3eyP1AVXpXUpRUuDutvPggo8890HPPO6p+BfPZ1STxB1bN62PXuRRgG1RMu+O3vfP78kGR+DWkJSUr4kDuX3LLhztNtTgyPY6BQbcF7SZBMNExGkf+B1LbUlDmXtd33U5QjAXzw==\"\n }\n }\n]\n\nThe following should be included in the http headers:
\nX-Dispatch-Key - same as with inbound endpoint
X-Dispatch-Signature - same as with inbound endpoint
The following conventions apply to all event processing:
\nexternal_id - This is the Enterprise's record ID
friendly_external_id (only for jobs) - this is an optional field. Very often systems have the technical \"ugly ID\" that only the techies in your organization know exists. And there is also a \"friendly ID\" that end users and customers use as references. If this is the case, then please put the \"ugly ID\" into the external_id and the \"friendly ID\" into friendly_external_id
updated_at - Use this to mark the time the event occured
The structures defined in \"From Dispatch\" sections are our canonical default. We like to keep these payloads small and relevant to make it easier and more obvious for you to process. However, if you think there are data elements that you need, please let us know and we should be able to configure it for you. Similarly (as described in the section above), if you already have your own preferred structure and/or format in which you prefer to receive the data, please let us know - there's a good chance we'll be able to accomodate you .
\nPlease be aware that we may put additional events in the stream as our product evolves. Although we will not change the names of attributes in the payload, it is possible that we'll add new attributes to the payload. Therefore make sure that your payload consumption will not break if a new attribute starts being included.
\nIf you are not using the outbound endpoint for picking up messages (see next section) then the payload will not contain the Message envelope. It will look as follows:
{\n \"type\": \"some_type\",\n \"payload\":\n {\n \"some_payload\": \"either the canonical described in this document or an agreed upon custom format\"\n }\n}\n\nWhere:
\ntype - e.g. job, appointment etc.
payload - data is the same as what is delivered in the Payload in the agent out endpoint.
The endpoint to send all inbound requests are:
\nProduction: https://connect.dispatch.me/agent/in
\nOur outbound sample code has some working examples for both canonical and customer payloads in a number of different programming languages. This should help you get going.
\nDispatch can support other types of outbound integrations such as sending webhooks to a provided endpoint, SFTP or FTP location if that is your preference (SFTP, FTP and other similar \"unusual\" use cases may incur an additional fee in order to support).
\n","_postman_id":"8eaf2873-77e7-41f0-bb32-5ccdc837d49f"},{"name":"Validation","item":[],"id":"3476fb12-0709-4dec-a06d-4742c95130a4","description":"Updates received on the Dispatch Platform may be received from various sources. Most updates will be made directly using the Dispatch apps but they may also be made via our gateway connected apps, such as Service Titan, Service Fusion and House Call Pro.
\nWhile we can guarantee adherence to strict data input when using the Dispatch apps for receiving field updates, we cannot guarantee that this strictness will be adhered to when updates are received from one of the gateways connected apps (simply because those apps have their own internal logic which are governed by the companies that own those apps).
\nAn example, might be what we call \"status messages\". When pausing a job in Dispatch you have the option of specifying a pause reason from a list that the user can select from. This most likely will not be the case when receiving a similar update from the gateway connected apps and therefore the pause reason may be different or missing in those cases. The same may be the case for other updates.
\nTherefore we advocate for a more lenient validation policy when receiving updates from Dispatch. Because our view is that it's better for you to receive as much info as is provided from the field rather than having some updates be blocked due to strict validation policies (e.g. in this case, if you validated a pause update for having a different pause reason -- or lacking any -- than what we've set up in Dispatch, you'd miss the update that the job was paused entirely). So our philosophy is that less complete information is better than no information when it comes to gateway connected updates.
\n","_postman_id":"3476fb12-0709-4dec-a06d-4742c95130a4"},{"name":"Polling Design Best Practices","item":[],"id":"9e6b027d-46d8-48f2-96ed-4ae5c009fc02","description":"Each time you poll the agent/out endpoint you should pull down using a maxNumberOfMessages of 10 (this is currently the highest number of messages you can request at a time). If the messages returned is equal to maxNumberOfMesssages you should poll again. Repeat until the queue is empty. In this way, you will clear out the queue each time you poll which ensures that your updates will be timely and the queue will remain low. The code samples incorporate this logic in them - be sure to follow this guidance!
Make sure to \"ack\" each message directly after downloading it. That is, you should NOT poll for 10 messages, process them all and then ack each message. Instead you should poll for 10 messages, process the first and then ack it, process the second and ack it and so on. This is important because there is an expiration (typically 30 seconds) to ack a polled message and if you do it after that time, the ack will be rejected and the message will stay in the queue until you poll it again. Again the code samples incorporate this logic in them, so if you follow the pattern shown you'll be in good shape.
\nSeparate polling the endpoint from the business logic to update your business system. Often business logic (including multiple API interplay steps) can be involved and slow the system down. You should instead download the messages into a local store (e.g. sql table) and \"ack\" immediately after which lets us know that you received the message. From there you can process into your business systems as necessary. Needless to say, if you process directly to your business system and that takes \"too long\", you will run into the expiration issue mentioned above.
\nOnly have a single process that polls the endpoint. If you have multiple processes polling the endpoint they can interfere with one another (as SQS makes messages invisible to other processes from the process being polled in order to prevent a message from being processed more than once). If you wish to employ multiple processes to poll the endpoint, then you should ensure that they are timed to alternate with one another and you should reach out Dispatch as we may need to tune the queue based on your polling strategy.
\nIf for some reason you get an exception while locally storing a message, do not ack the message. If you do, the message will disappear from the queue and there will be data loss. By not acking it, you are ensuring that the message remains on the queue for processing the next time you poll. However, please be aware that if you are repeatedly getting exceptions while locally storing a message, the queue will grow and will block processing due to the FIFO nature of the queue. Therefore you should be sure to research this event should it occur to prevent a backlog (which will have the affect of delaying the timely processing of messages sent from Dispatch)
\nYou can subscribe to Dispatch events in order to process updates into your system. The From Dispatch sections in this document describe the relevant use cases that you should follow. There are however some conventions that apply across the board and these are noted in the sections below.
\n","_postman_id":"55e918db-425e-4015-be05-d8a586b08a74"},{"name":"Postman","item":[],"id":"f5148e32-7c19-42f2-a429-9c64d2b8aac8","description":"While these docs have been created in postman and you can launch them in the postman desktop experience, the payload samples will not work within postman. This is because the connector requires HMAC authentication which is not currently supported in Postman. Instead, you will need to work within an environment like Python to get the examples working.
\n","_postman_id":"f5148e32-7c19-42f2-a429-9c64d2b8aac8"},{"name":"IP Whitelisting","item":[],"id":"21985f89-1f13-4204-bced-21af10612285","description":"If you require IP whitelisting you will need to white list the following IPs:
\nProduction:
\nSandbox:
\nYou should perform testing against our sandbox apps. Please use the following links:
\nIf you’re using an iPhone, you may receive this message when first opening the app (this only will happen for the sandbox app as it's not in the app store):
\n![](\"https://content.screencast.com/users/nvsimon/folders/Playbooks/media/e0ed0adc-b21e-4644-b5ac-0e336ecd3dc0/06.29.2018-15.38.png\")
\n\nGo to Settings | General | Device Management and trust the app:
\n![](\"https://content.screencast.com/users/nvsimon/folders/Playbooks/media/6fcbcd11-2f98-4c8f-8949-2d8d8397553b/06.29.2018-15.43.png\")
","_postman_id":"b6735f29-6e74-4cba-a990-5e87d38d3bb8"},{"name":"Questionaire","item":[],"id":"563a28eb-1b4c-46f8-bbaa-6f58777cec88","description":"If you have not yet engaged with the Dispatch team it would be helpful to respond to this questionaire. This will help clarify your use case and help us provide you with the necessary guidance for your use case.
\nBusiness model
\nDo you maintain your own W2 workforce or do you use contractors?
\nGeographical Areas
\nHow many geographical areas do you cover? Do any of your techs overlap between these locations?
\nAppointment Scheduling
\nWhat is your preferred method of setting up an appointment?
\nService Provider Setup
\nYou can either have the Service Providers set up “on the fly” (i.e. the first time they have a job sent to them they’ll receive a notification to get download the app etc.) or they can be set up in advance. What is your preference?
\nDecline Reasons
\nWhen contractors are sent a job they have the option to decline. First of all, should they have that option. Second of all, the following are the decline reasons they will see by default. Let us know if you’d like to adjust these:
\nComplete Reasons
\nWhen a job is complete there are various “complete reasons” that can be selected from. The following is what they will see by default. Let us know if you would like to adjust these:
\nSource System
\nIs your source system home grown or do you use a 3rd party product? If the latter, what product are you using? Which programming language will you be using?
\nCanonical/non-Canonical
\nThe playbooks describe canonical data structures for sending and receiving data. Will you be using these canonical structures or would you prefer to define your own (either for sending or receiving or both)?
\n","_postman_id":"563a28eb-1b4c-46f8-bbaa-6f58777cec88"},{"name":"FAQ","item":[{"name":"Why do I see a \"200 OK\"?","item":[],"id":"f7482974-5d46-4daa-8de4-83d9bc833409","description":"Why do I see an \"200 OK\" message in cases where the payload I sent through did not achieve the desired result?
\nThis is for 2 main reasons:
\nagent/in endpoint is a multi purpose endpoint. You will send data to this endpoint regardless of whether you're creating an organization, job, technician or something else entirely. The agent/in endpoint therefore is merely a way to receive requests that are then passed on to our lower level APIs for processing into Dispatch.Do you have a retry mechanism?
\nYes. Per above the agent/in endpoint does nothing else than receive inbound requests. It then passes it onto the Dispatch lower level services for processing to Dispatch (which includes the validation, mapping, cross-referencing/upsert logic and necessary API steps). And in that layer a retry mechanism is inbuilt such that if there is a period of disruption (500 errors) the retry mechanism will automatically kick in. This also means that Dispatch stores all requests sent to the connector agent/in endpoint regardless of whether it got successfully processed into Dispatch. And we have this archive at our disposal for analysis and replay purposes (if that action becomes necessary).
Given this, the only possible point of failure between a source system and Dispatch is if the agent/in endpoint is not available. And the only time that would happen is if AWS had some sort of outage which is a very rare occurrence. That said, in order to achieve an absolute fail safe design, we would recommend that you build in a retry mechanism when posting to our agent/in endpoint.
When I post to agent/out in rapid succession subsequent posts come up with an empty response. If I post again a little later, the response comes up again. Why is that?
\nThis is a feature of Amazon SQS which is the underlying technology and it is employed to prevent two parallel processes from processing the same message. By default this \"black out\" is 30 seconds but can be adjusted if necessary. This is typically something that is encountered while debugging in a development environment. We recommend that you follow the processing logic implemented in the code samples which will clear out the queue for each iteration.
\n","_postman_id":"38e2694d-c968-4ed8-84c7-9200cdb72f6a"},{"name":"Typical errors","item":[],"id":"beb9fbf7-86a0-4429-a1fa-3c015d9968c2","description":"What errors should I expect to see at the agent/out endpoint?
Almost all errors that you'll encounter will be during the initial development and testing phase. Once that stage has been passed, you'll find that errors are very few and far between. In fact, a key architectural goal of the connector is to maximize throughput and eliminate errors stopping integration to the extent possible. This is because the thing that is most disconcerting to end users is when there is a disruption in service. For example, if an invalid email is passed we will strip it out rather than stopping the integration. The same is true for invalid phone numbers. And therefore for all practical considerations, the following are the errors we tend to see in a production environment:
\nAs we have a strategic relationship with Salesforce and many of our typical prospects and clients use Salesforce we have built a Salesforce connector to make it super easy to integrate with Salesforce. Whatever your configuration!
\nLet's review that last point for a minute. We're fully aware that within 5 minutes of installing Salesforce inside your organization, you have utilized Salesforce's incredible extensible platform to add new custom fields, objects - you name it! Therefore it is a central tenet of our Salesforce integration that we are not tied to any specific Salesforce configuration. We are not tied to specific licensing. Whatever your current Salesforce implementation, no matter how highly customized (and believe us, we've seen incredibly customized Salesforce environments - doesn't phase us in the least) - we can integrate to it no problem!
\nAnother item worth mentioning is that we do have considerable experience on the Salesforce Platform and therefore our generally recommended implementation strategy is to let Dispatch focus on building the integration. In fact, you can consider us as an additional resource on your projects - in that we'll take care of the integration aspect. And of course, we'll do this with full transparency so that you can know and be sure what changes we are implementing into your environment. Based on this, a typical project implementation breaks down as follows:
\nThe above is a good separation of concerns - business logic vs. integration logic. And provides a clear delineation of who is responsible for which aspect. The example further illustrates and discusses this point.
\n","_postman_id":"0fbc2264-0c8e-4f6a-8e6d-9b35e079305d"},{"name":"Dispatch Connect and the Salesforce Connector","item":[],"id":"42e96984-9954-4984-a49c-cb76f92e7347","description":"So why would you want to use the Salesforce Connector given that we have our Dispatch Connect integration product (as evidenced by this playbook)?
\nDispatch Connect is used as our general purpose integration tool. The Salesforce connector essentially uses the power of Dispatch Connect behind the scenes. That is when we send updates from Salesforce we are sending it to our connect inbound endpoint using a custom (or non-canonical) payload structure for further processing on the Dispatch backend. And when we send updates from Dispatch to Salesforce we are leveraging our connect outbound layer.
\nWe just make it very easy to do that using Salesforce apex via our managed package.
\nWe then do all the transformational work as part of the Dispatch Connect mapping layer. Which means:
\nThis will be expanded on in the example.
\n","_postman_id":"42e96984-9954-4984-a49c-cb76f92e7347"},{"name":"Using Agile","item":[],"id":"ff0032bf-1dc9-4c15-8ca7-b1a46e415f06","description":"Given the preamble of the overview, it may come as no surprise that we like to follow an agile approach for Salesforce projects - if you allow us to do so! Experience has shown that visualizing the integration is the best way to approach a project as early as possible in the project lifecycle. Visualization allows concepts to be brought down from the abstract into the tangible and therefore serves to educate in very real terms how the systems can work together, how the integration can be built (and with what speed), and what kind of data flows between the systems and how it might look on either side of the divide. And of course it allows an iterative approach based on that experience. See something you like, or something you don't like? Well we can adjust that and meet again (typically in very short order ) to review the revised look and so on and so forth. In summary, a typical agile approach would typically work as follows:
\nHaving said all that, we'd encourage you to give Dispatch access to your sandbox at the earliest stage of the project. If possible, straight after the kick off!
\n","_postman_id":"ff0032bf-1dc9-4c15-8ca7-b1a46e415f06"},{"name":"Salesforce Dev Features","item":[{"name":"Dispatch Managed Package","item":[{"name":"Dispatch Connect Aligned Integration Product","item":[],"id":"95f99be0-442d-4aca-8ca3-0f6b9356bcf2","description":"New Salesforce integrations will use this product exclusively. As mentioned earlier in the documentation, the Salesforce Connector interacts with the Dispatch Connect product. This document describes in detail both the inbound and outbound integration flows.
\nInbound (Salesforce to Dispatch) - the managed package is used to send hmac encrypted payloads to the Dispatch Connect endpoint. The Dispatch Connect credentials for doing so are stored and encrypted in the Salesforce instance.
\nRequest/Response - in certain use cases, it may be necessary to use real time request/response integration features. Retrieving service provider availability is a typical use case for this. The Managed Package wraps around these API use cases to return the relevant data. The Dispatch credentials for doing so are stored and encrypted in the Salesforce instance.
\nOutbound (Dispatch to Salesforce) - Dispatch Connect interacts directly with the Salesforce instance to send updates back to Salesforce using a designated Salesforce user. Credentials for doing so are stored in Dispatch.
\nThis interacts directly with the lower level Dispatch APIs. The documentation for this can be viewed here.
\nNote: in new Salesforce integrations, it is unlikely that we'll be using any features of the legacy integration product.
\n","_postman_id":"780e3172-98a2-411b-ad9f-895841d9d392"}],"id":"7b1074d5-7132-4473-9282-7ef0f568162a","description":"This is part of the Dispatch integration product that interacts with the Dispatch APIs. The Managed Package contains features to support:
\n\nNew features added to the Dispatch Managed Package can be upgraded using the standard Salesforce Managed Package upgrade process.
\n","_postman_id":"7b1074d5-7132-4473-9282-7ef0f568162a"},{"name":"Dispatch Change Set","item":[],"id":"5bcc468b-7b59-4ead-b5a9-8dec1a9392b5","description":"This contains the triggers, classes and custom fields that we add to your environment. This allows us to get your specific Salesforce setup (objects, fields) and send over to Dispatch. In our latest iteration of our connector (and our recommended approach) the triggers and classes of this change set functions solely as a publisher of change in your Salesforce environment. We'll review this in detail in the example.
\n","_postman_id":"5bcc468b-7b59-4ead-b5a9-8dec1a9392b5"}],"id":"aa8f2c3e-2675-4d70-b660-130a56cb4422","description":"A Dispatch deployment with the Salesforce Connector typically consists of the following Salesforce technology features:
\n\n","_postman_id":"aa8f2c3e-2675-4d70-b660-130a56cb4422"},{"name":"Governor Limits","item":[],"id":"6fbaf866-a480-4cad-a1c1-8d05f5205823","description":"No we're not talking about excesses of power! As pretty much everyone knows Salesforce enforces limits on API usage and such like. So this section is to provide some insight on how we'll impact that with the Salesforce Connector.
\nThe short answer should be very little and we can make it smaller still! Allow us to explain...
\nTake a look at the example that will illustrate this (and shows our recommended approach). The following is required to send data from Salesforce to Dispatch:
\nSo typically, if we consider transactional data like Work Orders, you'd have the above occur for every relevant save that is made. So multiply that by the number of saves you typically make a day and you arrive at the usage to expect.
\nOther typical updates include:
\nGiven the above, we typically have negligible impact on governor limits. And believe us when we tell you that we have very highly dynamic Salesforce implementations (think \"dispatch board\" operation in Salesforce) - so it's not like we haven't been tested in this regard (and these projects are mostly on our older version of the Salesforce Connector which involve multiple API calls for every update as opposed to just the one with our latest product). We can say with confidence that governor limits have never been a concern of any kind in all our Salesforce projects to date (and we'll remove this sentence if and when that happens!)!
\nThat said, there is an efficient way to dramatically decrease the amount of API hits if that is still a concern - by orders of magnitude. And that is to use Salesforce scheduled jobs which would work as follows:
\nThe above approach will aggregate your changes and obviously reduce the number of times it needs to post to Dispatch.
\nWe'd generally recommend to have this on a frequent schedule of every minute or so, but that can be adjusted based on business need.
\nWe have followed this approach on various projects but the reasons have never been due to countering governor limits concerns although it definitely can be used for that.
\nAs mentioned earlier, the updates from Dispatch to Salesforce happen entirely on the Dispatch Connect side. There is typically no Salesforce component for this. While this is our recommended approach we have employed other approaches historically which include webhooks and the Salesforce event bus.
\nUsing our recommended approach, updates from Dispatch are sent in real time back to Salesforce. We use a Salesforce user to make those updates via the Salesforce API. So for example, when a status, schedule, note, attachment, custom form is modified on the Dispatch side and that change is relevant to be sent to Salesforce, we'll call the API for each update made.
\nSo following this approach updates would be pretty frequent because updates of these nature are frequent. But to our knowledge (informed by Salesforce consulting firms we've worked with in the past), external Salesforce API calls do not affect governor limits (though we could be wrong... and things sometime change with Salesforce!).
\nSo what are strategies to decrease the frequency of API calls from Dispatch if that still a concern?
\nGenerally we don't recommend queueing updates from Dispatch as we like to do these real time as real time tends to be important for such updates. So unless it is a necessity we'd advise against it. And if it is a necessity we'd encourage the schedule to be not more than every minute.
\n","_postman_id":"6fbaf866-a480-4cad-a1c1-8d05f5205823"},{"name":"From Salesforce to Dispatch","item":[{"name":"Example 1","item":[{"name":"Trigger","item":[],"id":"533087f3-b32b-442e-af6c-00e57ceef1c7","description":"Add a new trigger or update an existing trigger if you prefer with the snippet below. This should include the following:
\nOnly include the relevant events. So in our example, we know that Work Orders are never sent to Dispatch upon creation - that happens down the line. So we just include an on update event. If that's different in your case, then include an after insert event. It's not common but it's possible you may also need to include an on delete event (in the event you want it to cancel or similar on the Dispatch side)
Limit it to isafter
Call the trigger handler
\ntrigger WorkOrderTrigger on WorkOrder (after update) {\n // ----------------------\n // Dispatch\n // ----------------------\n if (Trigger.isafter) {\n DispatchTriggerHandler.JobToDispatch(Trigger.new, Trigger.oldMap);\n }\n // ----------------------\n}\n\nWe'll do these together because they pretty much happen that way. Include the snippet below in your DispatchTriggerHandler class.
We generally recommend creating the following datetime fields (which Dispatch typically does as part of the integration work):
\nDispatch_Send - used to indicate you want to send data to Dispatch
Dispatch_Last_Synced - used to indicate that the sync to Dispatch was successful
Last_Updated_from_Dispatch - used to indicate the last time an update was received from Dispatch
Note the following:
\nChange - this consist of the following
\nthe if (rec.Dispatch_Send__c != null) condition
Create a workflow that updates this Dispatch_Send field on the Work Order at the point that a Work Order should be sent. So whatever your business logic is to indicate that should happen – you just set up your workflow to set the Dispatch_Send field when you're ready to send. And if that business logic changes, just adjust the workflow to reflect that change. This separates the “sync to Dispatch” from the business logic required to sync it and creates a nice separation from a business logic/integration point of view.
Once this field is populated, it syncs and all future relevant updates are also synced to Dispatch. That is, if this field is populated but remains unchanged and another relevant Dispatch field based on your mapping document is updated – that will still sync as an update to Dispatch (and you can see this in the code as the condition is just checking that it's not null not that it has been updated).
\nrelevantFields containing a list of fields relevant to the integration and passing that into the dispconn.DispatchMappingHelper.getChangedFields helper and storing the result in changedFieldsMap
updatedFromSalesforce variable that checks if the update was made on the Salesforce side or via integration
check if changedFieldsMap and updatedFromSalesforceare true as a necessary condition for executing the query
Query - including a query to return all relevant fields and store in a list. In the example below, we've but that in recs. A query is only required if you need to query data from related records otherwise you can just send us the trigger data. We recommend including the following fields in the query for logging purposes: Dispatch_Last_Synced__c, LastModifiedBy.Name, LastModifiedDate
Send to Dispatch - exactly as shown! This uses a global function from the Salesforce Connector managed package.
\npublic class DispatchTriggerHandler {\n private static boolean firstRun = true;\n public static void JobToDispatch(List newList, Map oldMap){\n if (!firstRun) { return; }\n Set<Id> recIds = new Set<Id>();\n Map<Id, Map<String, Object>> changedFieldsMap = new Map<Id, Map<String, Object>>();\n Set<String> relevantFields = new Set<String>{\n 'Dispatch_Send__c', 'Subject', 'Description', 'Category__c', 'Sub_Category__c'\n }; \n for(Case rec : newList) {\n if (rec.Dispatch_Send__c != null) {\n Case oldRec = oldMap.get(rec.Id);\n changedFieldsMap = dispconn.DispatchMappingHelper.getChangedFields(oldRec, rec, relevantFields);\n Boolean updatedFromSalesforce =(oldRec.Last_Updated_from_Dispatch__c == rec.Last_Updated_from_Dispatch__c && \n oldRec.Dispatch_Last_Synced__c == rec.Dispatch_Last_Synced__c);\n if (changedFieldsMap.size() > 0 && updatedFromSalesforce) {\n recIds.add(rec.Id);\n }\n }\n }\n if (recIds.size() > 0) {\n List recs = [SELECT Id, Name, Dispatch_Last_Synced__c, LastModifiedBy.Name, LastModifiedDate, \n CaseNumber, Subject, Description, Category__c, Sub_Category__c, ContactEmail, ContactPhone, ContactId, Account.ShippingStreet, \n Account.ShippingCity, Account.ShippingState, Account.ShippingPostalCode, Account.Name, Contact.FirstName, Contact.LastName,\n Property__r.Name, Property__r.City__c, Property__r.State__c, Property__r.Zip__c\n //(SELECT Id, Description FROM CaseLineItems ORDER BY LineItemNumber)\n FROM Case \n WHERE Id IN :recIds]; \n }\n dispconn.DispatchMappingHelper.sendToDispatch(recs, changedFieldsMap, false);\n }\n}\n\nThis example only shows the method of getting data out of Salesforce. Because as mentioned in the sections above, writing data from Dispatch to Salesforce occurs entirely on the Dispatch Connect mapping side and therefore there's typically no Salesforce component required for it.
\nAs mentioned there are 4 components required for sending data from Salesforce to Dispatch. And they're all really simple!
\nTrigger for publish
\nChange for relevant data to remove unnecessary chattiness
\nQuery using SOQL for relevant objects and fields
\nPost to Dispatch
\nSo let's go through them.
\n","_postman_id":"5f88500b-87a3-4ffc-88ed-37f430ba4634"},{"name":"Example 2","item":[],"id":"ea7d0c81-4814-4ef7-8f59-3d32c10a56fb","description":"We don't really need to as the above illustrates how it's done and it's rinse and repeat for every other object you wish to send to Dispatch. But just for good measure we'll provide you with a snippet from the DispatchTriggerHandler class for sending over Account records (typically Service Providers) to Dispatch.
This follows the same paradigm as the one above. The differences include:
\nWe recommend including a Dispatch_Me checkbox (which Dispatch typically does as part of the integration work) to flag which of your Service Providers you wish to send over to Dispatch. And the code filters using that.
No need to crate a Dispatch_Send field as the Dispatch_Me checkbox is sufficient
No need to create a Last_Updated_from_Dispatch__c field as this integration is only 1 way to Dispatch (other than the sync confirmation which will be reflected in the Dispatch_Last_Synced__c field)
public static void AccountToDispatch(List newList, Map oldMap){\n if (!firstRun) { return; }\n firstRun = false;\n Set<Id> recIds = new Set<Id>();\n Map<Id, Map<String, Object>> changedFieldsMap = new Map<Id, Map<String, Object>>();\n Set<String> relevantFields = new Set<String>{\n 'Dispatch_Me__c', 'Name', 'AccountNumber', 'Phone', 'Email__c',\n 'ShippingStreet', 'ShippingCity', 'ShippingState', 'ShippingPostalcode', 'ShippingCountry'\n }; \n\n for(Account rec: newList) {\n if (rec.Dispatch_Me__c) {\n Account oldRec = oldMap.get(rec.Id);\n changedFieldsMap = dispconn.DispatchMappingHelper.getChangedFields(oldRec, rec, relevantFields);\n Boolean updatedFromSalesforce =(oldRec.Dispatch_Last_Synced__c == rec.Dispatch_Last_Synced__c);\n if (changedFieldsMap.size() > 0 && updatedFromSalesforce) {\n recIds.add(rec.Id);\n }\n }\n }\n if (recIds.size() > 0) {\n List recs = [SELECT Id, Name, Dispatch_Last_Synced__c, LastModifiedBy.Name, LastModifiedDate, \n AccountNumber, Phone, Email__c,\n ShippingStreet, ShippingCity, ShippingState, ShippingPostalcode, ShippingCountry\n FROM Account \n WHERE Id IN :recIds\n AND Dispatch_Me__c = true];\n }\n dispconn.DispatchMappingHelper.sendToDispatch(recs, changedFieldsMap, false);\n }\nAs mentioned in the sections above, writing data from Dispatch to Salesforce occurs entirely on the Dispatch Connect mapping side and therefore there's typically no Salesforce component required for it.
\nThat said, we wanted to provide you with guidance on what to expect in terms of updates sent to Salesforce. Dispatch will typically create any missing fields as part of the integration effort (except for form data, notes and attachments as those typically have business logic best taken care of by the business).
\nStatus/Status reason – typically Dispatch_Status, Dispatch_Status_Reason as strings
Last sync - best practice to let you know the time the update was successfully made to Dispatch (typically Dispatch_Last_Synced)
Error - best practice to let you know of the error in the event the sync failed to Dispatch (typically Dispatch_Error (255)will be cleared out the next time an update occurs from Salesforce.
Milestone timestamps - date/time accepted, scheduled, enroute, started, paused, completed, canceled
\nStart/end appointment window – corresponding date/time fields
\nErrors (inbound and outbound) will automatically be written to the dispconn__Dispatch_Log__c object. You can add this object to the Salesforce UI or you can query it in SOQL e.g.:
SELECT Id,Name, dispconn__Error__c, dispconn__Record_Id__c, dispconn__Entity_Name__c, dispconn__Direction__c, CreatedDate, LastModifiedDate \nfrom dispconn__Dispatch_Log__c \nwhere dispconn__Record_Id__c = '0017f00000rjhHlAAI'\norder by LastModifiedDate desc\n\nWe also recommend sending these errors to the Salesforce notification system so users can be proactively notified of these errors so they can take the corrective action. To do so, go to Customer Settings > Dispatch Global Settings and a setting titled Alert Notification Id to it. The value should be set to the result of this query:
SELECT Id FROM CustomNotificationType WHERE DeveloperName = 'Dispatch_Connect'
This API wraps around the Match Orgs core API and the response will be as documented there.
\nThe following is sample Apex code that you can use to invoke the API and interpret the response:
\nMap<String, Object> res = dispconn.DispatchMappingHelper.matchOrgs(new Map<String,String>{'postal_code' => '75024', 'trades' => String.join(new List<String>{'trade 1', 'trade 2'}, '|')});\nSystem.debug(JSON.serialize(res));\nfor (Object matchObj : (List<Object>)res.get('account_organizations')) {\n Map<String, Object> match = (Map<String, Object>)matchObj;\n System.debug(JSON.serialize(match));\n for (Object externalId : (List<Object>)match.get('external_ids')) {\n System.debug('Org external ID (ID in your system - use to update Salesforce):' + (String)externalId);\n break;\n }\n}\n\nThis API wraps around the Match Techs core API and the response will be as documented there.
\nThe following is sample Apex code that you can use to invoke the API and interpret the response:
\nMap<String, Object> res = dispconn.DispatchMappingHelper.matchTechnicians(new Map<String,String>{'postal_code' => '02446', 'appointment_duration_minutes' => '30', 'availability_start_time' => String.valueOf(dateInUtc), 'availability_end_time' => String.valueOf(dateInUtc),'trades' => String.join(new List<String>{'trade 1', 'trade 2'}, '|')});\nSystem.debug(JSON.serialize(res));\nfor (Object matchObj : (List<Object>)res.get('matches')) {\n Map<String, Object> match = (Map<String, Object>)matchObj;\n Map<String, Object> user = (Map<String, Object>)match.get('entity');\n System.debug(JSON.serialize(user));\n for (Object externalId : (List<Object>)user.get('external_ids')) {\n System.debug('User external ID (ID in your system - use to update Salesforce):' + (String)externalId);\n break;\n }\n for (Object slotObj : (List<Object>)match.get('slots')) {\n Map<String, Object> slot = (Map<String, Object>)slotObj;\n System.debug(JSON.serialize(slot)); // returns list of available times for tech\n }\n}\nGiven a file attachment uuid that you obtained from Dispatch you can use this method to retrieve the underlying file name and base64 string.
Please note that you'll need to add the following URLs to the Salesforce Remote Site Settings:
\nSample Usage:
\nMap payload = dispconn.DispatchMappingHelper.getFileUrl('7644eac6-575d-4f2b-b5e0-138c7819edae', true);\nsystem.debug('name: '+(String)payload.get('name'));\nsystem.debug('url: '+(String)payload.get('url'));\nsystem.debug('base64: '+(Blob)payload.get('base64'));\n\nGiven a Dispatch job can use this method to retrieve the all the PDF billing documents linked to it returned as base64 strings.
\nSample Usage:
\nMap pdfbase64StringMap = dispconn.DispatchMappingHelper.getBillingDocumentPdfs((String) dispatchJobId, new Map());\nfor (String billingDocId : pdfbase64StringMap.keySet()) {\n Object pdfbase64String = pdfbase64StringMap.get(billingDocId);\n Blob b = EncodingUtil.base64Decode(String.valueOf(pdfbase64String));\n}\n\nThe Salesforce managed package includes some global methods. These methods wrap around common use case Dispatch APIs such that you are able to make these API calls from Apex with a minimum of effort. They utilize the stored credentials of the managed package.
\n","_postman_id":"6ce24bf6-2933-4d2c-ab32-4a93974f5ee7"}],"id":"4468a0c3-45ab-49f8-9db4-ff81d71eb135","_postman_id":"4468a0c3-45ab-49f8-9db4-ff81d71eb135","description":""}],"id":"64745225-fe26-4221-8e33-55f554c3b9c9","_postman_id":"64745225-fe26-4221-8e33-55f554c3b9c9","description":""},{"name":"Quick Starts","item":[{"name":"DNM (Decentralized Network Management)","item":[{"name":"Direct Assign to Provider","item":[{"name":"To Dispatch","item":[{"name":"Jobs","id":"2b5006d1-2f8d-4cea-803a-4e20236e7cde","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"organization\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"organization\": {\n \"name\": \"Your Service Provider\",\n \"email\": \"your_service_provider@dispatch.me\",\n \"external_id\": \"your_enterprise_service_provider_id\",\n \"phone_number\": \"(555)013-0352\",\n \"always_create\": true,\n \"address\": {\n \"street_1\": \"3313 Maple Avenue\",\n \"postal_code\": \"90731\",\n \"city\": \"San Pedro\",\n \"state\": \"CA\"\n }\n }\n }\n },\n {\n \"header\": {\n \"record_type\": \"customer\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"external_id\": \"your_enterprise_service_provider_id-your_enterprise_customer_id\",\n \"external_organization_id\": \"your_enterprise_service_provider_id\",\n \"email\": \"email@dispatch.me\",\n \"phone_numbers\": [\n {\n \"number\": \"+15550913813\",\n \"primary\": true,\n \"type\": \"Mobile\"\n }\n ],\n \"home_address\": {\n \"street_1\": \"3913 Ford Street\",\n \"city\": \"Revere\",\n \"state\": \"MA\",\n \"postal_code\": \"02151\"\n }\n }\n },\n {\n \"header\": {\n \"record_type\": \"job\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"title\": \"Job title\",\n \"status\": \"offered\",\n \"description\": \"Some description.\\n\\n# Accepts *markdown*\",\n \"external_id\": \"your_enterprise_job_id\",\n \"friendly_external_id\": \"your_friendly_enterprise_job_id\",\n \"external_customer_id\": \"your_enterprise_customer_id\",\n \"external_organization_id\": \"your_enterprise_service_provider_id\",\n \"expected_duration\": 3600,\n \"symptom\": \"Some symptom\",\n \"service_fee\": 500,\n \"service_fee_precollected\": false,\n \"service_instructions\": \"instruction to tech\",\n \"contacts\": [\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"primary\": true,\n \"contact_methods\": [\n {\n \"value\": \"+15550913813\",\n \"method\": \"phone\",\n \"notify\": true\n },\n {\n \"value\": \"test@abc.com\",\n \"method\": \"email\",\n \"notify\": true\n }\n ]\n }\n ],\n \"address\": {\n \"street_1\": \"1213 Summer St\",\n \"street_2\": \"apt. 1\",\n \"postal_code\": \"01234\",\n \"city\": \"Boston\",\n \"state\": \"MA\"\n },\n \"service_type\": \"plumber\",\n \"_labels\": [\n 100,\n 101\n ],\n \"ui_options\": {\n \"show_decline\": true,\n \"accept_title\": \"Accept\",\n \"decline_title\": \"Decline\",\n \"reject_reasons\": [\n \"wrong_area|I don't service this address|true|false\",\n \"wrong_trade|I don't do this type of work|false|true\",\n \"no_availability|I can't do this job in time|false|false\",\n \"other|Other|true|true\"\n ]\n },\n \"equipment_descriptions\": [\n {\n \"manufacturer\": \"Acme\",\n \"model_number\": \"500\",\n \"serial_number\": \"01024\",\n \"installation_date\": \"2017-10-21T00:00:00Z\",\n \"equipment_type\": \"hvac\"\n }\n ],\n \"marketing_attributions\": [\n {\n \"content\": \"bingo\",\n \"campaign\": \"mamba\",\n \"source\": \"orca\",\n \"term\": \"glitter\",\n \"media\": \"twitter\"\n }\n ],\n \"suggested_times\": [\n {\n \"start_time\": \"2018-06-05T17:00:00+0000\",\n \"end_time\": \"2018-06-05T19:00:00+0000\"\n },\n {\n \"start_time\": \"2018-06-06T17:00:00+0000\",\n \"end_time\": \"2018-06-06T19:00:00+0000\"\n },\n {\n \"start_time\": \"2018-06-07T17:00:00+0000\",\n \"end_time\": \"2018-06-07T17:00:00+0000\"\n }\n ],\n \"custom_fields\": {\n \"do_not_survey\": \"yes\",\n \"arrival_type\": \"range\"\n }\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"We call it a Job. You might call it a Work Order, Service Order or something else. Potato, potāto. Anyway, you will be sending these over to us.
\nA job has the following main elements:
\nThough we are quite forgiving, a job cannot really be a job without some basic information, so please take care to include the following details:
\nid if you've pre-created those)We will not create duplicate records. Meaning if you send over the same organization or customer record more than once, the system is smart enough to detect they exist.
\nWe'd also recommend you include a valid customer email and mobile number as that will enhance the experience. Do try to avoid invalid entries such as jim@@abc.com and 555123 as if you don't manage that we'll be forced to strip them before processing.
Oh and lastly, we'd really encourage sending over your unique IDs into the external_id fields for the job and organization. This field is used for matching in order to process updates as described above.
Send this payload and voila - a job will be created in Dispatch!
\nIf you are providing a custom payload then you can skip this next section. Most of the fields in the payload should be self explanatory. But we do want to bring the following to your attention:
\nfriendly_external_id - this is an optional field. Very often systems have the technical \"ugly ID\" that only the techies in your organization know exists. And there is also a \"friendly ID\" that end users and customers use as references. If this is the case, then please put the \"ugly ID\" into the external_id and the \"friendly ID\" into friendly_external_idstatus - the default mapping expects the following values:description - this can accept markdown formattingcontacts - you can include this section to specify 1 or more contacts for the job. This can differ or be the same as to what you pass on the customer record.expected_duration - If relevant specify the expected duration of the job in seconds.suggested_times - This is an optional section. If you include it will offer the service provider these as \"suggested times\" that the customer has indicated are preferable.ui_options - This is an optional section. It allows you to specify reject reasons for a job offered to a service provider. You can use what's presented in this example or provider your own list. The format of the reject reasons uses the following format: value|friendly_label|show_text|require_text where:value - technical field value e.g. \"wrong_area\"friendly_label - e.g. \"Wrong Area\"show_text - true/false. If true, an additional free text field will displayrequire_text - true/false. Make free text required entry.custom_fields - you can specify any number of custom fields here. These will not show up on the front end by default, so please coordinate with Dispatch what your objective is, if using these.brand_id - if you want to customize the look and feel of notifications depending on the brand the job is created for, please reach out to Dispatch with the brands you wish to set up.labels - if you want to apply labels to jobs, please reach out to Dispatch with the values you wish to use before using this option (remove the leading \"_\" if you want to use this field).external_id passed here is unique per organization. This is probably not the case in your system, therefore you should prefix with the external ID of the organization as shown in the payload exampleorganization_id or external_organization_id into the job recordexternal_organization_id of \"contractor_1\" and later you update that to \"contractor_2\", the Dispatch Platform will automatically cancel the job for the first contractor and create another for the second.We call it an Organization. You might call it a Service Provider, Contractor, 3rd Party, Installer or something else. Tomato, tomāto.
\nNow the things is, you don't actually have to send these over to us separately. If you send these with the aforementioned job then we'll create them on the fly. However, sometimes it is preferred for these to be created separately in advance and if that's the case for you then you've come to the right place.
\nAt a minimum, please ensure you provide us with the following bits of information (although the more the merrier of course):
\nIt's also really good practice to include your unique organization ID in the external_id attribute as then you can reference that when sending jobs over.
Oh and definitely the address. We use that to determine the time zone and if it's omitted we're forced to default to EST. So you may want to pass this so the guys in CA can sleep in a little bit.
\nSend this payload and Bob's your contractor!
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"49cb6560-bb65-45f0-b90e-fa02251d342a"}],"id":"c5e28ae2-134f-4fa3-98dd-955bea2a89f0","event":[{"listen":"prerequest","script":{"id":"5007f813-77a2-4493-9dd4-70c24ae848bd","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"dc507a1a-af78-4f9d-894f-cdd583bbda3a","type":"text/javascript","exec":[""]}}],"_postman_id":"c5e28ae2-134f-4fa3-98dd-955bea2a89f0","description":""},{"name":"From Dispatch","item":[{"name":"Job Related Events","id":"ade1b10c-6eb7-445c-8bf2-affaaa45e78d","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"This describes the use cases for processing Job events. These events are wrapped in a job key ().
These are the cases that should be monitored:
\nJob events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"status\": \"some_status\",\n \"status_message\": \"some message\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"external_id\": \"your_system_id\"\n ]\n }\n }\n }\n ]\n }\n\nunscheduledrejectedstatus_messagecompletestatus_messageThis event is generated in the following circumstances:
\nTherefore:
\ncomplete event (not required in most cases)Note:
\nscheduled event will be generatedpausedstatus_message (see examples below)This event is generated in the following circumstances:
\ncanceledstatus_messageThis event is emitted when a job is canceled. Therefore:
\ncanceled event (not required in most cases)Sometimes jobs don't originate from you sending them directly to Dispatch. For example, if customers use a web page for requesting service those jobs could be sent to Dispatch. If you want to subscribe so that you can create them in your system then read on.
\nThis event is a little beefier than other events as it contains the details of the job which you presumably want to copy to your system.
\noffered \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"organization_id\": 11776,\n \"title\": \" Claim Details 206\",\n \"status\": \"offered\",\n \"status_message\": \"\",\n \"description\": \"some description\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"service_type\": \"air conditioning\",\n \"service_fee\": 0,\n \"address\": {\n \"street_1\": \"1755 Ridgeview Dr\",\n \"street_2\": \"\",\n \"postal_code\": \"76012\",\n \"city\": \"Arlington\",\n \"state\": \"TX\",\n \"country\": \"United States\",\n \"timezone\": \"America/Chicago\",\n \"latitude\": 32.7633905735029,\n \"longitude\": -97.1352367468659\n },\n \"external_id\": \"your_system_id\",\n \"customer\": {\n \"first_name\": \"James\",\n \"last_name\": \"Dodd\",\n \"company_name\": \"\",\n \"email\": \"devs+dodd@dispatch.me\",\n \"phone_number\": \"+15559803824\"\n }\n }\n }\n }\n ]\n }\n\nThis describes the use cases for processing Appointment events. These events are wrapped in an appointment key.
These are the cases that should be monitored:
\n*Only if appointment granularity is required, otherwise you should track these with the corresponding job events.
\nThere is both a job external_id and appointment external_id in this payload. If you are monitoring the appointment level you should use the appointment reference otherwise it will be sufficient to use the job reference.
Appointment events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"appointment\": {\n \"id\": 18663,\n \"external_id\": \"your_system_id\",\n \"status\": \"some_status\",\n \"job_id\": 30463,\n \"updated_at\": \"2018-05-18T10:08:38+0000\",\n \"start_time\": \"2018-05-19T15:00:00+0000\",\n \"end_time\": \"2018-05-19T16:00:00+0000\",\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n\nscheduledenroutestartedcompletecanceledThis describes the use cases for consuming notes and attachment events. These events are wrapped in an attachment element.
Processing notes:
\ndescription attribute and an attachment will have a file_token element as you'll see in the examples below. Use this for your branch logic.id so that it can be referenced later on. If the deleted_at is not null, it means the note has been deleted.Note events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"attachment\": {\n \"id\": 3675,\n \"entity_type\": \"Job\",\n \"entity_id\": 30463,\n \"description\": \"some note\",\n \"updated_at\": \"2018-05-18T10:14:51+0000\",\n \"deleted_at\": null,\n \"job\": {\n \"external_id\": \"your_system_id\"\n } \n }\n }\n }\n ]\n }\n }\n\nThere's nothing more to it. Just pick up the description and process to your system.
Attachment events will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"attachment\": {\n \"id\": 3676,\n \"entity_type\": \"Job\",\n \"entity_id\": 30463,\n \"file_token\": \"37f3cf22-f1c5-437c-a078-8608e25a0b2b\",\n \"name\": \"DispatchConnect.png\",\n \"updated_at\": \"2018-05-18T10:15:49+0000\",\n \"deleted_at\": null,\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n\nPlease refer to this section for a write up on how to render the image using the retrieved file token.
\n","urlObject":{"protocol":"https","path":["agent","out"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"ddc8ae76-f98e-4235-88a2-4d67657cb045"},{"name":"Survey Events","id":"91b901e3-d376-4f59-8ba0-9121361a8ccb","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"This describes the use cases for processing Survey events. These events are wrapped in an surveyresponse element.
Survey events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"surveyresponse\": {\n \"account_message\": \"Average\",\n \"account_rating\": 3,\n \"id\": 4361,\n \"job_id\": 30459,\n \"message\": \"Great!\",\n \"rating\": 5,\n \"updated_at\": \"2018-05-18T10:57:10+0000\",\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n }\n\nThe survey message is broken up as follows:
If you need to update your system based on updates made on the Dispatch platform then this section is for you! If you managed to successfully send a job to Dispatch then you will be able to sign in as a Dispatcher and Technician and work the job.
\nAs a general rule, an event will only appear in the stream if it's something that originated from the Dispatch Platform. This means that we will not echo updates that originated in your system back to you!
\nAnd very importantly, please be sure to follow these Polling Design Best Practices
\nThis section lists the typical events that we think you should be monitoring (see this section for additional Connect Use Cases). If you encounter a case that you think is not covered, please reach out to us to review.
\njob.unscheduledjob.rejected (with configurable reasons e.g. Incorrect Service Area, No Availability, Wrong Trade)job.complete (with configurable reasons e.g. Ready for Billing)job_paused (with configurable reasons e.g. No Show, Waiting for Parts, Cannot Contact Customer)job.canceled (with configurable reasons)job.offered (only necessary when the jobs do not get sent directly from your system)appointment.scheduledappointment.enrouteappointment.startedappointment.complete (only if you need to track at the appointment level - usually sufficient to use job.complete)appointment.canceled (only if you need to track at the appointment level - usually sufficient to use job.canceled)survey.submittednoteattachmentUse this section when the service provider assignment logic is performed in your system of record such that the job already comes with a service provider assigned when it hits Dispatch.
\n","event":[{"listen":"prerequest","script":{"id":"7f282b0f-a36e-4ad9-981d-888729fbd620","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"7fdfe78e-d992-4928-84cb-a3b70f24d401","type":"text/javascript","exec":[""]}}],"_postman_id":"da4b7616-8067-4be8-90f3-16c6c2a0c85e"},{"name":"Match","item":[{"name":"To Dispatch","item":[{"name":"Organizations","id":"b073f81f-b94b-455d-b53e-26aae60f526b","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\r\n {\r\n \"header\": {\r\n \"record_type\": \"organization\",\r\n \"version\": \"v3\"\r\n },\r\n \"record\": {\r\n \"name\": \"Your Service Provider\",\r\n \"email\": \"your_service_provider@dispatch.me\",\r\n \"external_id\": \"your_enterprise_id\",\r\n \"phone_number\": \"(555)010-0352\",\r\n \"address\": {\r\n \"street_1\": \"3310 Maple Avenue\",\r\n \"postal_code\": \"90731\",\r\n \"city\": \"San Pedro\",\r\n \"state\": \"CA\"\r\n }\r\n }\r\n },\r\n {\r\n \"header\": {\r\n \"record_type\": \"trade_account_org\"\r\n },\r\n \"record\": {\r\n \"external_id\": \"your_external_org_id\",\r\n \"trades\": [\"Trade 1\", \"Trade 2\", \"Trade 3\"],\r\n \"external_organization_id\": \"your_external_org_id\"\r\n }\r\n },\r\n {\r\n \"header\": {\r\n \"record_type\": \"service_area\",\r\n \"version\": \"v1\"\r\n },\r\n \"record\": {\r\n \"external_id\": \"your_external_org_id\",\r\n \"external_organization_id\": \"your_external_org_id\",\r\n \"service_area_type\": \"zcta5\",\r\n \"name\": \"Your Service Provider (recommend setting to the same value as your Service Provider name)\",\r\n \"postal_codes\": [\r\n {\r\n \"postal_code\": \"02446\"\r\n },\r\n {\r\n \"postal_code\": \"02447\"\r\n },\r\n {\r\n \"postal_code\": \"02488\"\r\n }\r\n ]\r\n }\r\n },\r\n {\r\n \"header\": {\r\n \"record_type\": \"billing_item\",\r\n \"version\": \"v2\"\r\n },\r\n \"record\": {\r\n \"title\": \"Widget\",\r\n \"item_type\": \"service\",\r\n \"description\": \"Widget Description\",\r\n \"external_id\": \"your_catalog_id\",\r\n \"external_organization_id\": \"your_external_org_id\",\r\n \"price\": 200,\r\n \"sku\": \"widget\",\r\n \"active\": true,\r\n \"trades\": [\r\n \"Trade 1\",\r\n \"Trade 2\"\r\n ],\r\n \"price_locked\": false\r\n }\r\n }\r\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"We call it an Organization. You might call it a Service Provider, Contractor, 3rd Party, Installer or something else. Tomato, tomāto.
\nFor the match scenario, you will want to create these records in advance... so that you can auto-assign the jobs to them.
\nAt a minimum, please ensure you provide us with the following bits of information (although the more the merrier of course):
\nOh and definitely the address. We use that to determine the time zone and if it's omitted we're forced to default to EST. So you may want to pass this so the guys in CA can sleep in a little bit.
\nSend this payload and Bob's your contractor!
\nIn order to leverage the match algorithm, you may also want to send over the additional payloads included in the example. These should be mostly self-explanatory, but here's an explanation in terms of what these are used for.
\nThis is used to assign trades to orgs which can be used to auto-match and will also be used for filtering purposes on the front end.
\nexternal_organization_id - this should match the external_id passed into the organization recordexternal_id - in most cases this should be the same as external_organization_idtrades - List of trades. Note that these should be user friendly as they are also displayed on the front end.This is used to zip code coverage areas to orgs which can be used to auto-match. The example here is set up using US postal codes, but we also support Canadian postal codes and tracts. See the \"Use Cases\" for examples of those.
\nexternal_organization_id - this should match the external_id passed into the organization recordexternal_id - in most cases this should be the same as external_organization_id.external_organization_id- for US postal codes set to zcta5. See Use Cases for other formats.postal_codes - Include all the zip codes covered in this sectionThis is the product catalog. This is not used for auto-assign and therefore is optional for match. It is included here because these can be limited to the trades defined above.
\nexternal_organization_id - this should match the external_id passed into the organization recordexternal_id - in most cases this should be the same as external_organization_id.item_type - product or servicetrades - Specify the trade list you want to link the billing item to.We call it an Offer. You might call it a Work Order, Service Order or something else. Potato, potāto.
\nThe essential difference between a Dispatch \"job\" vs. an \"offer\" is that while a job is always assigned to a provider, an offer is never initially assigned to a provider. That happens as part of a subsequent \"match\" operation or assignment via the Dispatch UI. Once that assignment happens, the offer is converted into a job and all the usual processing associated with jobs and statuses applies (see \"DNM Quick Start\").
\nA offer has the following main elements:
\nThough we are quite forgiving, a job cannot really be a job without some basic information, so please take care to include the following details:
\nWe will not create duplicate records. Meaning if you send over the same organization or customer record more than once, the system is smart enough to detect they exist.
\nWe'd also recommend you include a valid customer email and mobile number as that will enhance the experience. Do try to avoid invalid entries such as jim@@abc.com and 555123 as if you don't manage that we'll be forced to strip them before processing.
Oh and lastly, we'd really encourage sending over your unique IDs into the external_id fields for the offer. This field is used for matching in order to process updates as described above.
Send this payload and voila - an offer will be created in Dispatch!
\nIf you are providing a custom payload then you can skip this next section. Most of the fields in the payload should be self explanatory. But we do want to bring the following to your attention:
\nstatus - the default mapping expects the following values:description - this can accept markdown formattingcontacts - you can include this section to specify 1 or more contacts for the job. This can differ or be the same as to what you pass on the customer record.ui_options - This is an optional section. It allows you to specify reject reasons for a job offered to a service provider. You can use what's presented in this example or provider your own list. The format of the reject reasons uses the following format: value|friendly_label|show_text|require_text where:custom_fields - you can specify any number of custom fields here. These will not show up on the front end by default, so please coordinate with Dispatch what your objective is, if using these.trades - List of trades you want to include on the job which can be used in the matching algorith.If you want to invoke the match processing so that it runs immediately after the offer is, you should include the auto_assign_org record. See description here.
This describes the use cases for processing Offer events. These events are wrapped in a offer key ().
These are the cases that should be monitored:
\nOffer events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"offer\": {\n \"id\": 30462,\n \"status\": \"some_status\",\n \"status_message\": \"some message\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"external_id\": \"your_system_id\"\n }\n }\n }\n ]\n }\n\nThis indicates that the offer sent out was assigned and \"offered\" to an org (via auto or manual assign)
\nofferedThis indicates that the offer was canceled.
\ncanceledThis describes the use cases for processing Job events. These events are wrapped in a job key ().
These are the cases that should be monitored:
\nJob events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"status\": \"some_status\",\n \"status_message\": \"some message\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"external_id\": \"your_system_id\"\n ]\n }\n }\n }\n ]\n }\n\nunscheduledrejectedstatus_messagecompletestatus_messageThis event is generated in the following circumstances:
\nTherefore:
\ncomplete event (not required in most cases)Note:
\nscheduled event will be generatedpausedstatus_message (see examples below)This event is generated in the following circumstances:
\ncanceledstatus_messageThis event is emitted when a job is canceled. Therefore:
\ncanceled event (not required in most cases)Sometimes jobs don't originate from you sending them directly to Dispatch. For example, if customers use a web page for requesting service those jobs could be sent to Dispatch. If you want to subscribe so that you can create them in your system then read on.
\nThis event is a little beefier than other events as it contains the details of the job which you presumably want to copy to your system.
\noffered \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"organization_id\": 11776,\n \"title\": \" Claim Details 206\",\n \"status\": \"offered\",\n \"status_message\": \"\",\n \"description\": \"some description\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"service_type\": \"air conditioning\",\n \"service_fee\": 0,\n \"address\": {\n \"street_1\": \"1755 Ridgeview Dr\",\n \"street_2\": \"\",\n \"postal_code\": \"76012\",\n \"city\": \"Arlington\",\n \"state\": \"TX\",\n \"country\": \"United States\",\n \"timezone\": \"America/Chicago\",\n \"latitude\": 32.7633905735029,\n \"longitude\": -97.1352367468659\n },\n \"external_id\": \"your_system_id\",\n \"customer\": {\n \"first_name\": \"James\",\n \"last_name\": \"Dodd\",\n \"company_name\": \"\",\n \"email\": \"devs+dodd@dispatch.me\",\n \"phone_number\": \"+15559803824\"\n }\n }\n }\n }\n ]\n }\n\nThis describes the use cases for processing Appointment events. These events are wrapped in an appointment key.
These are the cases that should be monitored:
\n*Only if appointment granularity is required, otherwise you should track these with the corresponding job events.
\nThere is both a job external_id and appointment external_id in this payload. If you are monitoring the appointment level you should use the appointment reference otherwise it will be sufficient to use the job reference.
Appointment events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"appointment\": {\n \"id\": 18663,\n \"external_id\": \"your_system_id\",\n \"status\": \"some_status\",\n \"job_id\": 30463,\n \"updated_at\": \"2018-05-18T10:08:38+0000\",\n \"start_time\": \"2018-05-19T15:00:00+0000\",\n \"end_time\": \"2018-05-19T16:00:00+0000\",\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n\nscheduledenroutestartedcompletecanceledThis describes the use cases for consuming notes and attachment events. These events are wrapped in an attachment element.
Processing notes:
\ndescription attribute and an attachment will have a file_token element as you'll see in the examples below. Use this for your branch logic.id so that it can be referenced later on. If the deleted_at is not null, it means the note has been deleted.Note events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"attachment\": {\n \"id\": 3675,\n \"entity_type\": \"Job\",\n \"entity_id\": 30463,\n \"description\": \"some note\",\n \"updated_at\": \"2018-05-18T10:14:51+0000\",\n \"deleted_at\": null,\n \"job\": {\n \"external_id\": \"your_system_id\"\n } \n }\n }\n }\n ]\n }\n }\n\nThere's nothing more to it. Just pick up the description and process to your system.
Attachment events will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"attachment\": {\n \"id\": 3676,\n \"entity_type\": \"Job\",\n \"entity_id\": 30463,\n \"file_token\": \"37f3cf22-f1c5-437c-a078-8608e25a0b2b\",\n \"name\": \"DispatchConnect.png\",\n \"updated_at\": \"2018-05-18T10:15:49+0000\",\n \"deleted_at\": null,\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n\nPlease refer to this section for a write up on how to render the image using the retrieved file token.
\n","urlObject":{"protocol":"https","path":["agent","out"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"846f7b18-abb5-4a5d-ab8b-21f56fbca479"},{"name":"Survey Events","id":"25167c0e-4d78-4e8b-8013-5c0445b968b1","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"This describes the use cases for processing Survey events. These events are wrapped in an surveyresponse element.
Survey events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"surveyresponse\": {\n \"account_message\": \"Average\",\n \"account_rating\": 3,\n \"id\": 4361,\n \"job_id\": 30459,\n \"message\": \"Great!\",\n \"rating\": 5,\n \"updated_at\": \"2018-05-18T10:57:10+0000\",\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n }\n\nThe survey message is broken up as follows:
If you need to update your system based on updates made on the Dispatch platform then this section is for you! If you managed to successfully send a job to Dispatch then you will be able to sign in as a Dispatcher and Technician and work the job.
\nAs a general rule, an event will only appear in the stream if it's something that originated from the Dispatch Platform. This means that we will not echo updates that originated in your system back to you!
\nAnd very importantly, please be sure to follow these Polling Design Best Practices
\nThis section lists the typical events that we think you should be monitoring (see this section for additional Connect Use Cases). If you encounter a case that you think is not covered, please reach out to us to review.
\njob.unscheduledjob.rejected (with configurable reasons e.g. Incorrect Service Area, No Availability, Wrong Trade)job.complete (with configurable reasons e.g. Ready for Billing)job_paused (with configurable reasons e.g. No Show, Waiting for Parts, Cannot Contact Customer)job.canceled (with configurable reasons)job.offered (only necessary when the jobs do not get sent directly from your system)appointment.scheduledappointment.enrouteappointment.startedappointment.complete (only if you need to track at the appointment level - usually sufficient to use job.complete)appointment.canceled (only if you need to track at the appointment level - usually sufficient to use job.canceled)survey.submittednoteattachmentUse this scenario when you intend to take advantage of Dispatch's \"match\" algorithm for auto and/or manually assigning the provider record.
\n","event":[{"listen":"prerequest","script":{"id":"7f282b0f-a36e-4ad9-981d-888729fbd620","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"7fdfe78e-d992-4928-84cb-a3b70f24d401","type":"text/javascript","exec":[""]}}],"_postman_id":"ad21c8ce-8f34-4055-82ef-9dc6bed223b1"}],"id":"6ed5e5a3-ca51-4b06-ab97-7ff0a4f5c010","description":"The scenarios described in this section are relevant if you're an enterprise who employs a Decentralized Network (e.g. Contractor Network) for service fulfillment on behalf of your organization. We refer to this as our Decentralized Network Management (DNM) vertical.
\n","_postman_id":"6ed5e5a3-ca51-4b06-ab97-7ff0a4f5c010"},{"name":"(FSM) Field Service Management","item":[{"name":"To Dispatch","item":[{"name":"Organizations","id":"77e6b894-8415-4c4b-b028-8192c6e39b9c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\r\n\t{\r\n\t \"header\": {\r\n\t \"record_type\": \"organization\",\r\n\t \"version\": \"v3\"\r\n\t },\r\n\t \"record\": {\r\n\t\t \"name\" : \"Your Service Provider\",\r\n\t\t \"email\" : \"your_service_provider@dispatch.me\",\r\n\t\t \"external_id\": \"your_enterprise_id\",\r\n\t\t \"phone_number\" : \"(555)010-0352\",\r\n\t\t \"always_create\": true,\r\n\t\t \"address\": {\r\n\t\t \"street_1\": \"3310 Maple Avenue\",\r\n\t\t \"postal_code\": \"90731\",\r\n\t\t \"city\": \"San Pedro\",\r\n\t\t \"state\": \"CA\"\r\n\t\t }\r\n\t }\r\n\t}\r\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"We call it an Organization. You might call it a Franchise, Location, Office or something else. Tomato, tomāto.
\nNow the things is, you don't actually have to send these over to us separately. If you send these with the aforementioned job then we'll create them on the fly. However, in a typical W2 use case these are set up in advance and this section will tell you how to do just that.
\nAt a minimum, please ensure you provide us with the following bits of information (although the more the merrier of course):
\nIt's also really good practice to include your unique organization ID in the external_id attribute as then you can reference that when sending jobs over.
Oh and definitely the address. We use that to determine the time zone and if it's omitted we're forced to default to EST. So you may want to pass this so the guys in CA can sleep in a little bit.
\nLastly, the always_create flag will result in a new organization being created by circumventing Dispatch's dedup logic (matching on name, address, contact info). It will however not ignore the external_id that you pass through as IDs are, well, special.
We call it a User. You might call it an Employee, Tech or something else.
\nIf you maintain these users in your system of record you are going to want to keep them synchronized with Dispatch and this section will tell you how to do just that.
\nAt a minimum, please ensure you provide us with the following bits of information (although the more the merrier of course):
\nexternal_organization_id to link it back the organizationdispatcher (someone who can see other peoples jobs), technician (someone who can only see/work jobs assigned to them) or bothIt's also really good practice to include your unique user ID in the external_id attribute as then you can reference that when sending jobs over.
If you also wish to send over a photo for your technician, then please also include the profile_picture in your payload (can also be sent as a separate payload later if you prefer).
We call it a Job. You might call it a Work Order, Service Order or something else. Potato, potāto. Anyway, you will be sending these over to us.
\nA job has the following main elements:
\nThough we are quite forgiving, a job cannot really be a job without some basic information, so please take care to include the following details:
\nid if you've pre-created those)We will not create duplicate records. Meaning if you send over the same organization or customer record more than once, the system is smart enough to detect they exist. This therefore allows you, for example, to change the appointment time, assign and re-assign by just changing those values when sending the payload over.
\nWe'd also recommend you include a valid customer email and mobile number as that will enhance the experience. Do try to avoid invalid entries such as jim@@abc.com and 555123 as if you don't manage that we'll be forced to strip them before processing.
Oh and lastly, we'd really encourage sending over your unique IDs into the external_id fields for the job, appointment, user and organization. This field is used for matching in order to process updates as described above.
Send this payload and voila - a job will be created in Dispatch!
\nIf you are providing a custom payload then you can skip this next section. Most of the fields in the payload should be self explanatory. But we do want to bring the following to your attention:
\nfriendly_external_id - this is an optional field. Very often systems have the technical \"ugly ID\" that only the techies in your organization know exists. And there is also a \"friendly ID\" that end users and customers use as references. If this is the case, then please put the \"ugly ID\" into the external_id and the \"friendly ID\" into friendly_external_idstatus - the default mapping expects the following values:description - this can accept markdown formattingcontacts - you can include this section to specify 1 or more contacts for the job. This can differ or be the same as to what you pass on the customer record.custom_fields - you can specify any number of custom fields here. These will not show up on the front end by default, so please coordinate with Dispatch what your objective is, if using these.labels - if you want to apply labels to jobs, please reach out to Dispatch with the values you wish to use before using this option (remove the leading \"_\" if you want to use this field).external_id passed here is unique per organization. This is probably not the case in your system, therefore you should prefix with the external ID of the organization as shown in the payload exampleorganization_id or external_organization_id into the job record.always_create - we recommend you default to true (see write up here)external_organization_id of \"contractor_1\" and later you update that to \"contractor_2\", the Dispatch Platform will automatically cancel the job for the first contractor and create another for the second.time - estimated/actual start time of the appointmentduration - estimated/actual duration of the appointment (in seconds).window_start_time and window_end_time - earliest and latest arrival for the appointment (communicated to the customer)status - you generally want to set this to a value of scheduledexternal_id to external_job_id to the same valueexternal_user_id if you wish to assign or re-assign this should match the external ID you sent on the user record.external_secondary_user_ids - if you have additional users you want on the appointment, include them in an array.external_type_ids - you can specify different record types. This field is optional but if you do use it please ensure you've set up your appointment typesIf you want to leverage auto technician assignment, you should include this record. See explanation here.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"51d265a6-376c-485d-8cae-6a120e711978"}],"id":"35f635a4-2e5d-415e-b236-7270d6e62b43","event":[{"listen":"prerequest","script":{"id":"5007f813-77a2-4493-9dd4-70c24ae848bd","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"dc507a1a-af78-4f9d-894f-cdd583bbda3a","type":"text/javascript","exec":[""]}}],"_postman_id":"35f635a4-2e5d-415e-b236-7270d6e62b43","description":""},{"name":"From Dispatch","item":[{"name":"Job Related Events","id":"84abb1a8-8111-4319-abb0-12a4b27459b8","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"This describes the use cases for processing Job events. These events are wrapped in a job element.
These are the cases that should be monitored:
\nJob events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"status\": \"some_status\",\n \"status_message\": \"some message\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"external_id\": your_system_id\"\n }\n }\n }\n ]\n }\n\ncompletestatus_messageThis event is generated in the following circumstances:
\nTherefore:
\ncomplete event (not required in most cases)Note:
\nscheduled event will be generatedpausedstatus_messageThis event is generated in the following circumstances:
\ncanceledstatus_messageThis event is emitted when a job is canceled. Therefore:
\ncanceled event (not required in most cases)Sometimes jobs don't originate from you sending them directly to Dispatch. For example, if customers use a web page for requesting service those jobs could be sent to Dispatch. If you want to subscribe so that you can create them in your system then read on.
\nThis event is a little beefier than other events as it contains the details of the job which you presumably want to copy to your system.
\noffered \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"organization_id\": 11776,\n \"title\": \" Claim Details 206\",\n \"status\": \"offered\",\n \"status_message\": \"\",\n \"description\": \"some description\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"service_type\": \"air conditioning\",\n \"service_fee\": 0,\n \"address\": {\n \"street_1\": \"1755 Ridgeview Dr\",\n \"street_2\": \"\",\n \"postal_code\": \"76012\",\n \"city\": \"Arlington\",\n \"state\": \"TX\",\n \"country\": \"United States\",\n \"timezone\": \"America/Chicago\",\n \"latitude\": 32.7633905735029,\n \"longitude\": -97.1352367468659\n },\n \"external_ids\": [\n \"your_system_id\"\n ],\n \"customer\": {\n \"first_name\": \"James\",\n \"last_name\": \"Dodd\",\n \"company_name\": \"\",\n \"email\": \"devs+dodd@dispatch.me\",\n \"phone_number\": \"+15559803824\"\n }\n }\n }\n }\n ]\n }\n\nThis describes the use cases for processing Appointment events. These events are wrapped in an appointment element.
These are the cases that should be monitored:
\n*Only if appointment granularity is required, otherwise you should track these with the corresponding job events.
\nThere is both a job external_id and appointment external_id in this payload. If you are monitoring the appointment level you should use the appointment reference otherwise it will be sufficient to use the job reference.
Appointment events have the following basic payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"appointment\": {\n \"id\": 18663,\n \"status\": \"some_status\",\n \"job_id\": 30463,\n \"external_id\": your_system_id\",\n \"updated_at\": \"2018-05-18T10:08:38+0000\",\n \"start_time\": \"2018-05-19T15:00:00+0000\",\n \"end_time\": \"2018-05-19T16:00:00+0000\",\n \"job\": {\n \"external_id\": your_system_id\"\n }\n }\n }\n }\n ]\n }\n\nscheduledenroutestartedcompletecanceledThis describes the use cases for consuming notes and attachment events. These events are wrapped in an attachment element.
Processing notes:
\ndescription attribute and an attachment will have a file_token element as you'll see in the examples below. Use this for your branch logic.id so that it can be referenced later on. If the deleted_at is not null, it means the note has been deleted.Note events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"attachment\": {\n \"id\": 3675,\n \"entity_type\": \"Job\",\n \"entity_id\": 30463,\n \"description\": \"some note\",\n \"updated_at\": \"2018-05-18T10:14:51+0000\",\n \"deleted_at\": null,\n \"job\": {\n \"external_id\": \"your_system_id\"\n } \n }\n }\n }\n ]\n }\n }\n\nThere's nothing more to it. Just pick up the description and process to your system.
Attachment events will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"attachment\": {\n \"id\": 3676,\n \"entity_type\": \"Job\",\n \"entity_id\": 30463,\n \"file_token\": \"37f3cf22-f1c5-437c-a078-8608e25a0b2b\",\n \"name\": \"DispatchConnect.png\",\n \"updated_at\": \"2018-05-18T10:15:49+0000\",\n \"deleted_at: null,\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n\nPlease refer to this section for a write up on how to render the image using the retrieved file token.
\n","urlObject":{"protocol":"https","path":["agent","out"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"4d3156e9-0eba-43e2-9c19-42e8367a27a1"},{"name":"Survey Events","id":"c8691bd0-732d-4e55-8e74-831cbd703377","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"This describes the use cases for processing Survey events. These events are wrapped in an surveyresponse element.
Survey events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"surveyresponse\": {\n \"account_message\": \"Average\",\n \"account_rating\": 3,\n \"id\": 4361,\n \"job_id\": 30459,\n \"message\": \"Great!\",\n \"rating\": 5,\n \"updated_at\": \"2018-05-18T10:57:10+0000\",\n \"job\": {\n \"external_id\": \"your_system_id\"\n }\n }\n }\n }\n ]\n }\n }\n\nThe survey message is broken up as follows:
If you need to update your system based on updates made on the Dispatch platform then this section is for you! If you managed to successfully send a job to Dispatch then you will be able to sign in as a Dispatcher and Technician and work the job.
\nAs a general rule, an event will only appear in the stream if it's something that originated from the Dispatch Platform. This means that we will not echo updates that originated in your system back to you!
\nAnd very importantly, please be sure to follow these Polling Design Best Practices
\nThis section lists the typical events that we think you should be monitoring (see this section for additional Connect Use Cases). If you encounter a case that you think is not covered, please reach out to us to review.
\njob.complete (with configurable reasons e.g. Ready for Billing)job_paused (with configurable reasons e.g. e.g. No Show, Waiting for Parts, Cannot Contact Customer)job.canceled (with configurable reasons)job.offered (only necessary when the jobs do not get sent directly from your system)appointment.scheduledappointment.enrouteappointment.startedappointment.complete (only if you need to track at the appointment level - usually sufficient to use job.complete)appointment.canceled (only if you need to track at the appointment level - usually sufficient to use job.canceled)survey.submittednoteattachmentThe scenarios described in this section are relevant if you're an enterprise who either:
\nWe refer to this as our Field Service Management (FSM) vertical.
\nAlthough - and this is important - Franchises come in many shapes and sizes and some Franchise business workflows may more closely model our DNM rather than WFM vertical. We will help you determine the best practice usage of Dispatch during the early stages of the project.
\nThe FSM connector requirements are similar to those of the Decentralized Network (DNM). The primary differences are in the following areas:
\nTo Dispatch
\nFrom Dispatch
\nThe above is of course \"typical\". Your use case may vary and if so we'd love to hear how, so please do reach out.
\n","event":[{"listen":"prerequest","script":{"id":"93ad9f98-e558-47eb-aeab-7db4c40ed85f","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"85edd22c-3ae8-4ba2-8aeb-abf05367ca54","type":"text/javascript","exec":[""]}}],"_postman_id":"ba5a53b2-8b99-4080-9ec1-ad085b5b7fe6"},{"name":"Gateway","item":[{"name":"From Dispatch","item":[{"name":"Job Created","id":"52e3123a-a650-4faa-bdb1-5e2541110e73","request":{"method":"POST","header":[],"body":{"mode":"raw","raw":""},"url":"https://connect-sbx.dispatch.me/agent/out","description":"We call it a Job. You might call it a Work Order, Service Order or something else. Potato, potāto. Anyway, you will be receiving these from us. Jobs coming from the Dispatch Platform will have the following payload structure (this describes the core subset of fields that you will see in the actual payload):
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"source_id\": 123,\n \"source\": \"American Pie\",\n \"organization_id\": 11776,\n \"organization_external_id\": \"enterprise_contractor_id\",\n \"title\": \" Claim Details 206\",\n \"status\": \"offered\",\n \"status_message\": \"\",\n \"description\": \"some description - used internally for rendering at Dispatch. We recommend you don't use this field\",\n \"symptom\": \"some symptom at the job level if relevant\",\n \"service_instructions\": \"some internal description\",\n \"service_fee\": 130,\n \"service_type\": \"air conditioning\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"address\": {\n \"street_1\": \"1755 Ridgeview Dr\",\n \"street_2\": \"\",\n \"postal_code\": \"76012\",\n \"city\": \"Arlington\",\n \"state\": \"TX\",\n \"country\": \"United States\",\n \"timezone\": \"America/Chicago\",\n \"latitude\": 32.7633905735029,\n \"longitude\": -97.1352367468659\n },\n \"external_id\": \"enterprise_job_system_id\",\n \"customer\": {\n \"id\": 1234,\n \"external_id\": \"enterprise_customer_system_id\",\n \"first_name\": \"James\",\n \"last_name\": \"Dodd\",\n \"company_name\": \"\",\n \"email\": \"devs+dodd@dispatch.me\",\n \"phone_number\": \"+15559803824\"\n },\n \"equipment_descriptions\": [\n {\n \"manufacturer\": \"Acme\",\n \"model_number\": \"500\",\n \"model_name\": \"heater\",\n \"serial_number\": \"01024\",\n \"equipment_type\": \"hte\",\n \"installation_date\": \"2017-10-21T00:00:00Z\",\n \"location\": \"2nd floor\",\n \"symptom\": \"ivr not working\",\n \"custom_fields\": {\n \"field1\": \"may vary per brand\"\n }\n }\n ],\n \"custom_fields\": {\n \"field1\": \"may vary per brand\"\n },\n \"marketing_attributions\": [\n {\n \"content\": \"bingo\",\n \"campaign\": \"mamba\",\n \"source\": \"orca\",\n \"term\": \"glitter\",\n \"media\": \"twitter\"\n }\n ],\n \"ui_options\": {\n \"show_decline\": true,\n \"reject_reasons\": [\n \"incorrect_service_area\",\n \"no_availability\",\n \"wrong_trade\"\n ],\n \"complete_reasons\": [\n \"ready_for_billing\",\n \"customer_does_not_want_service\"\n ],\n \"pause_reasons\": [\n \"waiting_for_parts\",\n \"no_show\",\n \"waiting_on_authorization\"\n ], \n \"cancel_reasons\": [\n \"provider_canceled\",\n \"customer_canceled\"\n ]\n }\n }\n }\n }\n ]\n }\n}\n\nSome important things to note:
\ndescription field contains markdown data which is used for rendering purposes on the Dispatch Platform. Which is why you may find that this field contains a lot of # and \\* characters and may not be all that friendly in its plain text format. Therefore as a general rule, we recommend that you do not use this field for integration - the values within it should be contained within the other discrete fields of the payload. If you do wish to use this field then we'd recommend that you either render this in a markdown enabled control on your end or remove the markdown text to make it easier to read. Please do not parse this field for specific data as there is no guarantee that the structure of this description text will change in future iterations potentially breaking your integration.ui_options key contains reason codes that are offered on the front end when certain actions are taken. These will vary per brand. These are fed back through to the brand for visibility. Therefore it is highly recommended that you pick these up and incorporate into your flow. This includes:show_decline - if true then the contractor can \"decline\" or \"reject\" the job that they have been offeredreject_reasons - only relevant if show_decline is set. Contains the list of reasons codes that the user can select from when rejecting/decliningcomplete_reasons - list of reasons the user can select from when a job is being completedpause_reasons - list of reasons the user can select from when when a job is being paused or placed on holdcancel_reasons - list of reasons the user can select from when canceling a jobIf an enterprise cancels a job it will come over with the following structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"job\": {\n \"id\": 30462,\n \"status\": \"canceled\",\n \"status_message\": \"\",\n \"updated_at\": \"2018-05-18T10:05:46+0000\",\n \"external_id\": enterprise_job_system_id\"\n ]\n }\n }\n }\n ]\n }\n\nIt is up to you to decide whether and how to handle this event (or if you want to ignore entirely let us know so we can turn off).
\n","urlObject":{"protocol":"https","path":["agent","out"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"d5d9c280-7a8f-4d4e-9c46-9b3af2cbc7bd"}],"id":"73c9ef8a-8b32-4a3f-b598-b84b21a95112","description":"This section documents the following use cases:
\nReceive jobs from Dispatch
\nJob cancelations from Dispatch
\nVery importantly, please be sure to follow these Polling Design Best Practices (if you plan to use the polling strategy)
\n","event":[{"listen":"prerequest","script":{"id":"8d13775e-aa1a-4a2a-b4b4-4d8a909d3b51","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"b504eccb-88b3-4d6d-a274-e36036afb880","type":"text/javascript","exec":[""]}}],"_postman_id":"73c9ef8a-8b32-4a3f-b598-b84b21a95112"},{"name":"To Dispatch","item":[{"name":"Job","id":"a99ddffe-00b1-4491-9d88-6781c2cd8014","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/in","description":"When you send through a status update send over the following:
\n [{\n \"header\": {\n \"record_type\": \"job\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"id\": 555,\n \"organization_id\": \"the value you received from Dispatch\",\n \"source_id\": \"the value you received from Dispatch\",\n \"status\": \"see status list below\",\n \"status_message\": \"optional reason for status\",\n \"resolution\": \"optional resolution text\",\n \"pause_description\": \"optional additional message when pausing job\"\n }\n }]\n\nPlease try to map the status to one of the following values:
unscheduled - job is accepted by Service Provider
\nrejected - job is rejected by Service Provider
\nscheduled (to indicate \"arrived on site\" or \"enroute\" - see below for processing logic of this status)
\ncomplete
\npaused (to indicate that the job is on hold - see below for an example)
\ncanceled
\nValues in the list above appearing in bold are the critical job milestone statuses that should be sent over to make the connector effort valuable. The others are optional (but definitely recommended if you have them).
\nUse the status_message if you want to pass in a reason code. For example, you might send through a complete status with a reason of \"Customer No Show\".
To report that the technician is enroute set the following:
\n{\n \"status\": \"scheduled\",\n \"status_message\": \"enroute\"\n}\n\nTo report that the technician has arrived on site set the following:
\n{\n \"status\": \"scheduled\",\n \"status_message\": \"started\"\n}\n\nTo report that you tried to contact the custom set the following:
\n{\n \"status\": \"paused\",\n \"status_message\": \"cannot_contact_customer\",\n \"pause_description\": \"optional wordier description\"\n}\n\nWhen you schedule or reschedule an appointment send over the following:
\n [{\n \"header\": {\n \"record_type\": \"appointment\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"organization_id\": \"the value you received from Dispatch\",\n \"source_id\": \"the value you received from Dispatch\",\n \"status\": \"scheduled\",\n \"time\": \"2018-10-30T22:00:00.000Z\",\n \"duration\": 14400,\n \"job_id\": 555,\n \"external_id\": \"your_unique_id\",\n \"reschedule_reminder\": true\n }\n }]\n\nWhere:
\ntime - this is the scheduled start window of the appointment
duration - this is the duration of the appointment window in seconds
external_id - our jobs can have multiple appointments so please include your unique ID so we can know which one to update. If you only have a single appointment per job and you're not sure which value to use you can just repeat the value in the job_id over here.
reschedule_reminder - (optional) please note that when you reschedule an appointment, a notification will not automatically be sent through to the brand. This is because rescheduling can be a very frequent event which can result in \"spamming\" the brand with updates. Therefore we require a specific indication that you want this update to be reflected and you can use this to do so.
This is an optional but recommended update. You should only send through notes that are brand facing.
\nWhen you send through notes please send the following structure:
\n [{\n \"header\": {\n \"record_type\": \"attachment\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"organization_id\": \"the value you received from Dispatch\",\n \"job_id\": 555,\n \"external_id\": \"your unique id\",\n \"description\": \"some note\"\n }\n }]\n\nThis is an optional but recommended update. You should only send through attachments that are brand facing.
\nWhen you send through attachments please send the following structure:
\n [{\n \"header\": {\n \"record_type\": \"attachment\",\n \"version\": \"v3\"\n },\n \"record\": {\n \"organization_id\": \"the value you received from Dispatch\",\n \"job_id\": 555,\n \"external_id\": \"your unique id\",\n \"file\": \"base64encodedstring\",\n \"name\": \"your_file_name.jpg\"\n }\n }]\n\nUpdates you send back to Dispatch will be sent back through to the Enterprise. This section describes the updates that we are looking to receive. Though we encourage sending over all updates you deem relevant, the following is the recommended minimum set of updates:
\nAcceptance - assuming you have an acceptance step
\nSchedule
\nComplete
\nNotes - It would be also be very beneficial to receive notes too.
\nWe would strongly recommend that you send us all relevant job related statuses (and brand facing notes if relevant) that your system generates. If you do so, we will provide you with the exact payload to send over for each of those use cases. To help guide you, think about categorizing your statuses into the following general \"family\" of statuses:
\nNot Yet Scheduled (e.g. accepted, pending)
\nSchedule Change (e.g. schedule, re-schedule)
\nWork In Progress (e.g. OMW, started)
\nHold Status (e.g. follow up, waiting for parts, request auth, no show)
\nCompleted (e.g. work complete, customer canceled)
\nPlease note that if you are set up to use a single set of API credentials to send updates then please include the following in your http header:
\nRecordType: gatway\n\nSend this over to Dispatch when you want to connect a provider. This will notify Dispatch... who will then subsequently match it up with the appropriate provider on the Dispatch platform. In the event that Dispatch is unable to perform a match with the details provided, our team will reach out to yours for additional information.
\nIn the event you want Dispatch to notify your system upon successful activation, you will need to provide Dispatch with an endpoint to do so. If we do, the payload we send back will contain the following (if you want to include additional data elements let us know):
\n{\n \"external_organization_id\": \"your_provider_id\",\n \"organization_id\": \"the_matched_dispatch_id\"\n}\n\nAdditional notes:
\nRequired attributes
\nexternal_organization_id - this is the ID for the provider in your system
name
Include an http header RecordType: gateway_provision
You should include as much identifying detail as possible but at a minimum either:
\nphone_number
\naddress.state
\nThe app_id is a constant value that we will provide to you (likely the name of your company)
In the API creds - pass in whatever information is needed to authenticate to your API (in the event you want us to perform this step)
\nIn the event you want to offboard a previously onboarded provider, you will need to send over this payload.
\nAdditional notes:
\nThe organization_id is the dispatch Provider ID included in what we sent back to you using your endpoint (in the event you're doing this step). So you'll need to store this somewhere in your system.
Include an http header RecordType: gateway_deprovision
What is the processing of onboarding a new service provider on the Dispatch Gateway?
\nFirst of all, we'd recommend that we walk before we run. That is, let's get an MVP gateway integration set up with Dispatch before worrying about how to streamline the onboarding process. The process should be iterative. Also we should consider the need for optimizing the onboarding (and potentially offboarding) in lieu of how many service providers we realistically anticipate coming on board.
\nWith that said, while the onboarding processing can be streamlined, the process by necessity requires some human input. This is because Dispatch has thousands of service providers on its platform and we need to be sure that we match the correct service provider on our platform with the one on yours. There is no magic bullet here as there's no guarantee that the address, email, contact info that we have will be the same as yours.
\nThat said, the good news is that the effort for this matching will likely fall on Dispatch's side. To this end, if you're interested in streamlining this process the following is the process we recommend:
\nAdd a process in your app where a user can request connecting with Dispatch
\nWhen they do so, post the \"onboarding\" payload
\nDispatch will receive this request, do the validation, and then set this up (at which point they are connected). This typically takes a few hours or less.
\nIf you want verfication that the connection has taken place, you will need to provide Dispatch with an endpoint that we can hit for this.
\nFor offboarding, send a request to the same endpoint per the \"offboarding\" payload (this update will take effect immediately)
\nPlease also note that the onboarding and offboarding payloads require a special set of \"application keys\" that we will provide to you (only applicable for these payloads).
\n","_postman_id":"acbba8fe-8962-47a2-bf2a-21573419f9ee"},{"name":"Do updates get sent to all brands?","item":[],"id":"f0738b44-1f21-4638-bf43-6563447fce99","description":"The short answer is yes. Once you're connected with Dispatch your updates will go to whichever brand is consuming the data, including new ones who have yet to be connected to Dispatch!
\n","_postman_id":"f0738b44-1f21-4638-bf43-6563447fce99"},{"name":"How do we know which brand source the job is for?","item":[],"id":"f0ac4617-cecf-4042-82f2-119c4d1f5303","description":"The payload includes a source_id and source field. We'd recommend using the source_id field as that is more reliable and will not change. Dispatch can provide you the source IDs of the sources you are interested in upon request.
That is entirely between the brand and the service provider! In other words, the service provider should reach out to the brand if they're interested in performing work for them. Dispatch is not involved in that conversation. Once that service provider has been set up, then jobs they receive will begin arriving on the Dispatch platform (obviously provided that the brand is integrated with Dispatch).
\n","_postman_id":"e689b3b5-8517-4996-927a-1b0c1a709fcc"},{"name":"Syncing technicians","item":[],"id":"ac4bd85d-9dc6-4e77-8c23-4f8d060d7ba0","description":"We are some times asked whether the assigned technician can be synced to Dispatch. The short answer is no. The following is the explanation in case you're interested in understanding the reasons for this (if not, just skip):
\n\n\nFirst of all, it should be mentioned that brands typically don't care who performed the work (which technician). They just need to know which subcontractor organization is doing the work and visibility into that work. And the gateway integration gives them this visibility.
\n
\n\nSecondly, syncing techs for enroute events would send out the the default \"on my way\" notification to the customer who is then able to track their arrival. However, when the technician is not using the Dispatch mobile app (which is typically the case as they're using the your mobile app, the customer will not be able to do this tracking which can negatively impact that experience.
\n
\n\nFinally, on a more technical note, technician assignment requires syncing over the technician records from your system to Dispatch and ongoing maintenance of those records (create/update/deactivate). This would add considerable complexity to the integration as it would, by its very nature, involve a lot more moving parts.
\n
Having said all that, if you know the brand is interested in knowing which technician was assigned (the only reason to justify such a sync would be for brand visibility), please let us know which brand is requesting this so we can understand the business reason behind this and perhaps we can come up with a creative solution!
\n","_postman_id":"ac4bd85d-9dc6-4e77-8c23-4f8d060d7ba0"},{"name":"Round Robin and Jump Ball","item":[],"id":"10084c6a-a2d6-4900-a592-2a4f38e171b1","description":"Some jobs are created via an offer strategy called Round Robin and Jump Ball. Both involve sending the job out for to multiple service providers and only one of those will ultimately service the job. For both of these cases, it is necessary for the service provider to accept the job in order to win it. And therefore we cannot send these type jobs to the gateway app until it has been accepted or otherwise that would constitute an unfair advantage for gateway connected organizations.
\nTLDR: Round Robin and Jump Ball jobs must be accepted in the Dispatch app before they will flow to the gateway app.
\nThat's really all you need to know but if interested here is a description of these 2 strategies.
\nRound Robin - Job is offered to service providers in sequence and is often time bound before it expires. If that job expires or is rejected it will go to the next service provider in the list.
\nJump Ball - Job is offered to all service providers at once and whoever accepts first wins the job.
\nThe scenarios in this section are relevant to you if you offer a BMS (Business Management Solution) field service product solution and you wish to receive jobs and send updates via the Dispatch Platform.
\nThe standard flow for this use case is depicted as follows:
\n![\"Gateway](\"https://raw.githubusercontent.com/Nahis/dispatchme/master/gateway_overview.jpg\")
\n\nEnterprise sends a job to Dispatch
\nYou pick this job up from Dispatch and process into your system (either via polling or webhook)
\nYou send through updates to Dispatch which typically include:
\nMilestone status e.g. accept, scheduled, complete
\nNotes
\nThe exception flow for this use case is as follows:
\nEnterprise sends through a cancelation
\nYou send through a cancelation
\nWhether you choose to implement all are part of these use cases (or beyond) is up to you.
\nIn addition to the code samples, we've also provided some code examples that you can use to draw inspiration from. You'll have to adapt this to the way that your APIs work in your system but these should show some of the thinking that will need to be applied as your build the integration.
\nWe have also provided a UAT test script that you can use to test the connector (we will have discussed the various scenarios mentioned in this script such that it will be clear which ones are relevant to your use case).
\nWhat is the processing of onboarding a new service provider on the Dispatch Gateway?
\nFirst of all, we'd recommend that we walk before we run. That is, let's get an MVP gateway integration set up with Dispatch before worrying about how to streamline the onboarding process. The process should be iterative. Also we should consider the need for optimizing the onboarding (and potentially offboarding) in lieu of how many service providers we realistically anticipate coming on board.
\nWith that preamble out of the way, while the onboarding processing can be streamlined, the process by necessity requires some human input. This is because Dispatch has thousands of service providers on its platform and we need to be sure that we match the correct service provider on our platform with the one on yours. There is no magic bullet here as there's no guarantee that the address, email, contact info that we have will be the same as yours.
\nThat said, the good news is that the effort for this matching will likely fall on Dispatch's side. To this end, if you're interested in streamlining this process the following is the process we recommend:
\nAdd a process in your app where a user can request connecting with Dispatch
\nWhen they do so, fire off a json webhook that will include the org name, address, and contact info (Dispatch will tell you which endpoint to send this to)
\nDispatch will receive this request, do the validation, and then set this up (at which point they are connected). This typically takes a few hours or less.
\nIf you want verfication that the connection has taken place, you will need to provide Dispatch with an endpoint that we can hit for this.
\nFor offboarding, you can similarly send a request to the same endpoint (this update will take effect immediately)
\nAdd your company’s appointment types. When you create aan appointment, you’ll be able specify a type from this list. The only required attribute is the name.
You can also specify a default duration for the appointment which is relevant if your users can create appointments using the Dispatch front end.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"446f139f-a8b6-40ee-9d5b-0903c9ac0ce5"}],"id":"525da6e7-f643-48e3-8f4b-bfe7f93b8466","event":[{"listen":"prerequest","script":{"id":"83a86be5-3e5d-449a-ab03-719c36608f4e","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"4abc03ca-7dda-4135-8498-224bc5e9b27e","type":"text/javascript","exec":[""]}}],"_postman_id":"525da6e7-f643-48e3-8f4b-bfe7f93b8466","description":""},{"name":"Auto Assign","item":[{"name":"Auto Assign Technician","id":"071da253-b7f7-4383-9b78-6c88fc8ef989","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"[\r\n {\r\n \"header\": {\r\n \"record_type\": \"auto_assign_technician\",\r\n \"version\": \"v3\"\r\n },\r\n \"record\": {\r\n \"external_id\": \"your_enterprise_job_id\",\r\n \"external_appointment_id\": \"your_enterprise_job_or_appointment_id\",\r\n \"external_technician_ids\": [\r\n \"your_user_id1\",\r\n \"your_user_id2\"\r\n ],\r\n \"external_secondary_technician_ids\": [\r\n \"your_user_id3\",\r\n \"your_user_id4\"\r\n ],\r\n \"appointment_duration_minutes\": 60,\r\n \"address\": {\r\n \"street_1\": \"3913 Ford Street\",\r\n \"city\": \"Revere\",\r\n \"state\": \"MA\",\r\n \"postal_code\": \"02151\"\r\n },\r\n \"postal_code\": \"02151\",\r\n \"availability_start_time\": \"2018-05-18T10:00:00+0000\",\r\n \"availability_end_time\": \"2018-05-18T14:00:00+0000\",\r\n \"override_availability\": false,\r\n \"two_tech\": false\r\n }\r\n }\r\n]","options":{"raw":{"language":"json"}}},"url":"https://connect-sbx.dispatch.me/agent/in","description":"If you want to leverage auto technician assignment via the Dispatch Match algoritm, you should include this record. Also note, that auto assignment might fail in which case, you will be informed about this via this outbound event.
\naddress - should match that of the job you're trying to schedulepostal_code - should match that of the job you're trying to scheduletwo_techs - if set to false only the primary technician IDs are checked for auto-assignment otherwise both primary and secondary technicians are checked.If you want to leverage auto org assignment via the Dispatch Match algoritm, you should include this record. Also note, that auto assignment might fail in which case, you will be informed about this via this outbound event.
\ntrades - This should match the trades passed into the offer. If you don't pass this in, the match won't filter by trade.postal_code - This should match the postal code you included on the job.Every Line Item used on a Billing Document (Estimate/Invoice) must be linked to a master product catalog item (or Billing Item).
\nTherefore you should either create these on the fly as you create your estimates and invoices (as shown in the example in the section for \"Billing Documents\") or you can create these as a separate integration thread as shown here.
\nIf you provide a trade list linked to the billing items, it will restrict the use of the billing items to those trades.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"251a6ca2-7eb7-4255-98b0-e21864069022"},{"name":"Billing Documents","id":"367ae5dd-53b8-4f2c-bd64-1bbba8145dfc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\r\n{\r\n\t\"header\": {\r\n\t\t\"record_type\": \"billing_item\",\r\n\t\t\"version\": \"v2\"\r\n\t},\r\n\t\"record\": {\r\n\t \"title\" : \"Line 1\",\r\n\t \"item_type\" : \"service\",\r\n\t \"external_id\": \"your_catalog_id_1\",\r\n\t \"external_organization_id\": \"your_organization_id\"\r\n\t }\r\n},\r\n{\r\n\t\"header\": {\r\n\t\t\"record_type\": \"billing_item\",\r\n\t\t\"version\": \"v2\"\r\n\t},\r\n\t\"record\": {\r\n\t \"title\" : \"Line 2\",\r\n\t \"item_type\" : \"service\",\r\n\t \"external_id\": \"your_catalog_id_2\",\t \r\n\t \"external_organization_id\": \"your_organization_id\"\r\n\t }\r\n},\r\n{\r\n\t\"header\": {\r\n\t\t\"record_type\": \"billing_document\",\r\n\t\t\"version\": \"v2\"\r\n\t},\r\n\t\"record\": {\r\n\t \"external_id\": \"your_document_id\",\r\n\t \"external_job_id\" : \"your_job_id\",\r\n\t \"external_organization_id\": \"your_organization_id\",\r\n \"external_customer_id\": \"your_customer_id\",\r\n \"customer\": {\r\n \"full_name\": \"John Doe\",\r\n \"address\": {\r\n \"city\": \"Portland\",\r\n \"state\": \"OR\",\r\n \"country\": \"United States\",\r\n \"street_1\": \"33400 NE 24th Ave.\",\r\n \"postal_code\": \"33400\"\r\n }\r\n },\t \r\n\t \"doc_type\" : \"Estimate\",\r\n\t \"title\": \"Billing Document Title\",\r\n\t \"description\" : \"Billing Document Description\",\r\n\t \"discount_amount\": 10,\r\n\t \"lines\" : [\r\n\t {\r\n\t \"external_billing_item_id\": \"your_catalog_id_1\",\r\n\t \"title\" : \"Line 1\",\r\n\t \"description\" : \"Line 1 Description\",\r\n\t \"qty\" : 10,\r\n\t \"price\" : 1.00,\r\n\t \"taxable\": false\r\n\t },\r\n\t {\r\n\t \"external_billing_item_id\": \"your_catalog_id_2\",\r\n\t \"title\" : \"Line 2\",\r\n\t \"description\" : \"Line 2 Description\",\r\n\t \"qty\" : 10,\r\n\t \"price\" : 2.00,\r\n\t \"taxable\": false\r\n\t }\r\n\t ]\r\n\t}\r\n}\r\n]\t"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"A Billing Document must be attached to an existing job. And each line of the Billing Document must be linked to a valid Product Catalog or Billing Item.
You should pay special attention to the following:
\nstatus - Make sure you map this appropriately - the valid values are described in the introskip_customer_signature - If you are passing a value of won (for an Estimate) or balance_outstanding (for an Invoice) you will need to set this to true as you are circumventing the signature capture form on the front end.In Dispatch we refer to both Estimates and Invoices as Billing Documents. This is because Estimates and Invoices are two sides of the same coin and are structurely very similar. We differentiate between them use the doc_type attribute on the Billing Document.
A Billing Document consists of a header and details section:
\nproduct or service that you are selling and every line item must be linked to a master \"billing item\".To illustrate the difference between a line item and billing item consider the following:
\nThe typical flow for billing documents is as follows:
\nPlease note the following:
\n\"action\": \"delete\" in the header sectionCalendar Events are tasks that are not linked to a customer. They generally reflect employee internal activities. Examples include:
\nPlease include a file name with extension so we know how to render.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"b41c4a4d-39a2-4c07-b8fe-29f05dd31658"},{"name":"Custom Form","id":"184ca510-fc55-45d3-be0b-b3a125243739","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"[\r\n {\r\n \"header\": {\r\n \"record_type\": \"custom_form\"\r\n },\r\n \"record\": {\r\n \"external_job_id\": \"your_id\",\r\n \"form_id\": \"wfm_custom_form_your_custom_form_name\",\r\n \"form_data\": [{\r\n \"custom_field_1\": \"custom_field_1_value\",\r\n \"custom_field_2\": \"custom_field_2_value\"\r\n }]\r\n }\r\n }\r\n]","options":{"raw":{"language":"json"}}},"url":"https://connect-sbx.dispatch.me/agent/in","description":"If you want to update the custom form via the API you can do so using this.
\nPlease note that currently custom forms are set up via Dispatch, so please reach out to obtain the relevant custom form name and schema and we'll send along (the fields you place in the form_id and form_data section will need to match these.
Use this include job trades on your jobs (and optionally use them for match filtering).
\nItems appearing in the list here should match the master list of trades that you provided Dispatch.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"deadf444-aaa8-4807-bd1e-07e0c2a69a11"},{"name":"Suggested Times","id":"4257f959-5f0f-4884-903a-9bf01e1e8e4d","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"suggested_times\"\n },\n \"record\": {\n \"external_job_id\": \"your_job_id\",\n \"suggested_times\": [\n {\n \"start_time\": \"2022-06-13T12:00:00.000Z\",\n \"end_time\": \"2022-06-13T16:00:00.000Z\"\n },\n {\n \"start_time\": \"2022-06-14T12:00:00.000Z\",\n \"end_time\": \"2022-06-15T16:00:00.000Z\"\n }\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Use this include suggested times on your jobs.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"4257f959-5f0f-4884-903a-9bf01e1e8e4d"},{"name":"Job Attribution/Sources","id":"b14ed28d-f8b9-4a52-ad41-8be8ffee3dd1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"admin\": true,\n \"record_type\": \"job_attribution\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_attribution_id\",\n \"external_organization_id\": \"your_external_org_id\",\n \"name\": \"Cold Call\"\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Add your company’s job sources. When you create a job, you’ll be able to attribute it to a source from this list.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"b14ed28d-f8b9-4a52-ad41-8be8ffee3dd1"}],"id":"3f0583c1-2600-4607-9349-65ee7e194b67","event":[{"listen":"prerequest","script":{"id":"5f4e7f24-0518-4201-9136-130a742e8b87","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"0c28df90-0583-4d97-b2e1-0dab690758be","type":"text/javascript","exec":[""]}}],"_postman_id":"3f0583c1-2600-4607-9349-65ee7e194b67","description":""},{"name":"Organizations","item":[{"name":"Configuration Settings","item":[{"name":"Configuration Settings","id":"4175422f-7151-4893-9734-4fe040ea4822","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"header\": {\r\n \"record_type\": \"config\",\r\n \"version\": \"v1\"\r\n },\r\n \"record\": {\r\n \"external_organization_id\": \"your_external_org_id\",\r\n \"organization_customer\": {\r\n \"app\": {\r\n \"profileBuilderEnabled\": true,\r\n \"profileBuilderV2\": [\r\n {\r\n \"brand\": \"google\",\r\n \"link\": \"http://google2\",\r\n \"text\": \"Please leave a review on Google!\"\r\n },\r\n {\r\n \"brand\": \"facebook\",\r\n \"link\": \"http://facebook2\",\r\n \"text\": \"Please like us on Facebook!\"\r\n }\r\n ]\r\n }\r\n },\r\n \"organization_dispatcher\": {\r\n \"app\": {\r\n \"canSeeInbox\": true,\r\n \"canSeeMobileInbox\": true,\r\n \"canSeeQuickbooks\": true,\r\n \"integrations\": {\r\n \"remove\": [\r\n \"Free Booking Page\"\r\n ]\r\n }\r\n }\r\n },\r\n \"organization_reminders\": [\r\n {\r\n \"name\": \"test reminder\",\r\n \"type\": \"customer_pre_appointment\",\r\n \"min_hours_out\": 15,\r\n \"max_hours_out\": 33,\r\n \"include_weekends\": true,\r\n \"reminder_schedules\": [\r\n {\r\n \"timezone\": \"America/New_York\"\r\n }\r\n ],\r\n \"local_hour\": \"12\",\r\n \"local_minute\": \"0\",\r\n \"schedule\": \"0 12 * * SUN,MON,TUE,WED,THU,FRI,SAT\",\r\n \"days_of_week\": \"SUN,MON,TUE,WED,THU,FRI,SAT\"\r\n }\r\n ]\r\n }\r\n}"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Speak to your Dispatch rep about what settings you wish to apply defaults for and they will supply you with the list of relevant notifications settings as part of the project. The payload will resemble the example provided.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"4175422f-7151-4893-9734-4fe040ea4822"}],"id":"05d675b1-776f-49d4-a8b4-72744b992e70","event":[{"listen":"prerequest","script":{"id":"7f485883-a546-48ce-9189-caeab4213903","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"137c9d46-04e5-4731-8167-8fdfbd82ef8a","type":"text/javascript","exec":[""]}}],"_postman_id":"05d675b1-776f-49d4-a8b4-72744b992e70","description":""},{"name":"Service Areas","item":[{"name":"Service Area (Tracts)","id":"bc1239d0-fd24-49d5-b49a-7d777e6a1000","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"service_area\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_service_area_external_id\",\n \"external_organization_id\": \"your_external_org_id\",\n \"service_area_type\": \"tract\",\n \"name\": \"recommend setting this to your company name\",\n \"census_tracts\": [\n \"41017000800\",\n \"41017000900\",\n \"41017001001\"\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Using tract/fips codes
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"bc1239d0-fd24-49d5-b49a-7d777e6a1000"},{"name":"Service Area (Postal Codes)","id":"1f6fe2cf-151b-4802-995f-be559225f32a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"service_area\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_service_area_external_id\",\n \"external_organization_id\": \"your_external_org_id\",\n \"service_area_type\": \"zcta5\",\n \"name\": \"recommend setting this to your company name\",\n \"postal_codes\": [\n {\n \"postal_code\": \"02446\"\n },\n {\n \"postal_code\": \"02447\"\n },\n {\n \"postal_code\": \"02488\"\n }\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Using US Postal Codes
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"1f6fe2cf-151b-4802-995f-be559225f32a"},{"name":"Service Area (Canadian Postal Codes)","id":"c619a8fb-d02b-4d3d-bd1f-b87af0d854c5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"service_area\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_service_area_external_id\",\n \"external_organization_id\": \"your_external_org_id\",\n \"service_area_type\": \"fsaldu\",\n \"name\": \"recommend setting this to your company name\",\n \"canadian_postal_codes\": [\n \"H7M 6J3\",\n \"P9A 8M7\"\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Using Canadian Postal Codes
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"c619a8fb-d02b-4d3d-bd1f-b87af0d854c5"}],"id":"7dddabb0-534b-4b94-8d7e-0d6533b38d41","description":"Define your geographic service areas based on:
\nAn example of each is provided below.
\nIf you only have a single service area per organization (usually the case), you should set the external_id to the same value as the external_organization_id
Use this to specify the trades assigned to organizations. These can be used as assignment filters.
\nPlease note that before you can use these APIs you will need to provide Dispatch with the master list of trades you intend to use (at the moment we don't have a publicly exposed API to set up the master list). This master list is what you will reference in the trades list and therefore you should:
Using tract/fips codes
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"5e927083-1006-46a5-a7cb-d6a4404da42c"},{"name":"Service Area (Postal Codes)","id":"77285d5e-850c-4922-9089-7fde67f5d2fc","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"service_area\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_service_area_external_id-your_user_id\",\n \"name\": \"recommend setting to user name\",\n \"service_area_type\": \"zcta5\",\n \"postal_codes\": [\n {\n \"postal_code\": \"02446\"\n },\n {\n \"postal_code\": \"02447\"\n },\n {\n \"postal_code\": \"02488\"\n }\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Using US Postal Codes
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"77285d5e-850c-4922-9089-7fde67f5d2fc"},{"name":"Service Area (Canadian Postal Codes)","id":"05827888-f6cc-4f12-a27b-4866ab10c2d3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"service_area\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_service_area_external_id-your_user_id\",\n \"name\": \"recommend setting to user name\",\n \"service_area_type\": \"fsaldu\",\n \"canadian_postal_codes\": [\n \"H7M 6J3\",\n \"P9A 8M7\"\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Using Canadian Postal Codes
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"05827888-f6cc-4f12-a27b-4866ab10c2d3"}],"id":"ab32546d-2dac-4d4b-9176-01202daea230","description":"Define your geographic service areas based on:
\nAn example of each is provided below.
\nIf you only have a single service area per organization (usually the case), you should set the external_id to the same value as the external_organization_id
Use this to add a photo for the user. Please include a file name with extension so we know how to render.
\n","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"26e7239b-42f0-4264-9292-e22defbc3172"},{"name":"User Tags","id":"418e11ad-c6a6-4ffd-b830-dc8c9c3b08de","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"user_tag\",\n \"version\": \"v1\"\n },\n \"record\": {\n \"external_id\": \"your_external_user_id\",\n \"external_user_id\": \"your_external_user_id\",\n \"key\": \"ranking_score\",\n \"value\": \"44\"\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","urlObject":{"protocol":"https","path":["agent","in"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"418e11ad-c6a6-4ffd-b830-dc8c9c3b08de"},{"name":"User Trades","id":"e5915a1c-089d-4fa6-a55d-61ada3206b7e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"[\n {\n \"header\": {\n \"record_type\": \"trade_account_user\"\n },\n \"record\": {\n \"external_id\": \"your_external_user_id\",\n \"trades\": [\n \"Trade 1\",\n \"Trade 2\",\n \"Trade 3\"\n ]\n }\n }\n]"},"url":"https://connect-sbx.dispatch.me/agent/in","description":"Use this to specify the trades assigned to users. These can be used as assignment filters.
\nPlease note that before you can use these APIs you will need to provide Dispatch with the master list of trades you intend to use (at the moment we don't have a publicly exposed API to set up the master list). This master list is what you will reference in the trades list and therefore you should:
Tags are used to tag users with attributes. For example, you add a ranking via tags to find preferred technicians via the availability algorithm
\n","event":[{"listen":"prerequest","script":{"id":"b33765f2-cdd2-4b6c-8dc8-1a881241cfa3","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"2e099808-4adc-4a2e-8738-f2e0a39f2b19","type":"text/javascript","exec":[""]}}],"_postman_id":"5afd58c6-ee4d-4ed0-903b-17cabb57c65a"}],"id":"92fbd710-4a4a-448a-80c8-24abb790b612","event":[{"listen":"prerequest","script":{"id":"5007f813-77a2-4493-9dd4-70c24ae848bd","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"dc507a1a-af78-4f9d-894f-cdd583bbda3a","type":"text/javascript","exec":[""]}}],"_postman_id":"92fbd710-4a4a-448a-80c8-24abb790b612","description":""},{"name":"From Dispatch","item":[{"name":"Ack/Error","item":[{"name":"Acks","id":"34a8e4dd-e86f-4b76-a241-f2c3e912e399","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"If you wish to receive acks of transactions successfully sent to the Dispatch Platform you can subscribe to this event. By default this is not sent back into the event stream so please let us know if you want this enabled.
\nmsg_id will contain the value in the \"MessageId\" header when sending to the inbound endpoint (see code samples) so you're able to correlate the ack with a specific inbound transaction.
This event indicates an ack that a transaction got processed successfully on the Dispatch side. It does not indicate that the Dispatcher acknowledged the job.
\nAnd just like any other event you'll need send an update to agent/out to remove this from the queue (yes you'll need to acknowledge the acknowledgement!)
These will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [{\n \"ID\": \"some_id\",\n \"Put\": {\n \"ack\": {\n \"id\": 555,\n \"external_id\": \"your_id\",\n \"msg_id\": \"your_message_id\",\n \"action\": \"inbound_ack\",\n \"model\": \"job\",\n \"data\": {\n \"organization_id\": 11789,\n \"external_id\": \"enterprise_system_id\"\n }\n }\n }\n }]\n } \n\nWhere:
\nid - the corresponding ID of the created entity in Dispatch in case you wish to store it (optional)external_id - the id in your systemmodel - job for job, organization for organization etc.If you wish to receive notification of transactions that errored out you can subscribe to this event. By default this is not sent back into the event stream so please let us know if you want this enabled.
\nWe attempt to only send \"fixable\" errors to this endpoint. That is, errors that occurred due to bad data to this endpoint. These generally tend to be errors in the 400 range.
\nmsg_id will contain the value in the \"MessageId\" header when sending to the inbound endpoint (see code samples) so you're able to correlate the err with a specific inbound transaction.
As a general rule, the Dispatch Platform does everything to avoid transactions being rejected. As long as the minimal amout of data for a transaction is available the transaction will succeed. As such, we believe that errors are likely to occur during the testing phase of the project and thereafter should be very few and far between.
\nThese will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": \"some_id\",\n \"Put\": {\n \"err\": {\n \"payload\": {\n \"err\": {\n \"data_type\": \"job\",\n \"external_id\": \"your_id\",\n \"msg_id\": \"your_message_id\",\n \"message\": \"Problem writing job ({\\\"errors\\\":{\\\"status\\\":[\\\"is not included in the list\\\"],\\\"workflow\\\":[\\\"Job status is not in given workflow\\\"]}})\"\n }\n }\n }\n }\n }\n ]\n }\n\nStartFragment
\nexternal_id - the id in your systemdata_type - job for job, organization for organization etc.EndFragment
\n","urlObject":{"protocol":"https","path":["agent","out"],"host":["connect-sbx","dispatch","me"],"query":[],"variable":[]}},"response":[],"_postman_id":"eb00efba-c837-4f29-a6fa-f36505e59d84"}],"id":"f4658708-f3a1-4cf5-bd32-2b452d2b2acf","description":"The processing mentioned in this section is optional.
\n","event":[{"listen":"prerequest","script":{"id":"8ec37094-07f7-4927-a352-65e2de578f25","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"56c17ef4-2948-437e-a43e-f6b57814aa96","type":"text/javascript","exec":[""]}}],"_postman_id":"f4658708-f3a1-4cf5-bd32-2b452d2b2acf"},{"name":"Auto Assign Fail","item":[{"name":"Auto Assign Tech","id":"fde46862-b2ec-4017-abb1-acf7bd42adce","request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"If a technician auto assign action was unsuccessful, you will receive the following response:
\nThese will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [{\n \"ID\": \"some_id\",\n \"Put\": {\n \"ack\": {\n \"external_id\": \"external_job_id\",\n \"external_appointment_id\": \"external_job_or_appointment_id\",\n \"msg_id\": \"your_message_id\",\n \"action\": \"inbound_ack\",\n \"model\": \"auto_assign_technician\",\n \"ack_message\": \"No technicians found for availability window\",\n \"api_response\": {\n \"matches\": null\n }\n }\n }\n }]\n } \n\nIf org auto assign action was unsuccessful, you will receive the following response:
\nThese will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [{\n \"ID\": \"some_id\",\n \"Put\": {\n \"ack\": {\n \"id\": 555,\n \"data\": {\n \"external_id\": \"external_offer_id\"\n },\n \"msg_id\": \"your_message_id\",\n \"action\": \"inbound_ack\",\n \"model\": \"auto_assign_org\",\n \"ack_message\": \"No matching organizations found\",\n \"api_response\": {\n \"matches\": null\n }\n }\n }\n }]\n } \n\nThis describes the use cases for processing Estimate events. These events are wrapped in an estimate key.
Valid values for the status fields are:
draftwonlostThese events will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": \"a9ce6d53-dc32-51f8-81b4-3a00f47c5bdf\",\n \"Put\": {\n \"estimate\": {\n \"description\": null,\n \"discount_amount\": {\n \"currency\": \"USD\",\n \"text\": \"$30.00\",\n \"value\": \"30.00\"\n },\n \"discount_percent\": null,\n \"doc_type\": \"Estimate\",\n \"external_id\": \"your_estimate_id\",\n \"id\": 4697,\n \"invoice_id\": null,\n \"job\": {\n \"external_id\": \"your_enterprise_id\"\n },\n \"job_id\": 383147,\n \"lines\": [\n {\n \"billing_item_id\": null,\n \"id\": \"d9d0016b-554b-4748-9b00-0cf6aa7ff02c\",\n \"billing_item\": {\n \"external_id\": \"your_catalog_id\"\n }\n \"markup\": 0,\n \"price\": {\n \"currency\": \"USD\",\n \"text\": \"$3.33\",\n \"value\": \"3.33\"\n },\n \"price_with_markup\": {\n \"currency\": \"USD\",\n \"text\": \"$3.33\",\n \"value\": \"3.33\"\n },\n \"qty\": 2,\n \"taxable\": true,\n \"title\": \"\",\n \"total\": {\n \"currency\": \"USD\",\n \"text\": \"$6.66\",\n \"value\": \"6.66\"\n }\n }\n ],\n \"number\": \"1005\",\n \"paid\": false,\n \"po_number\": \"asfdfdasdf\",\n \"status\": \"draft\",\n \"subtotal\": {\n \"currency\": \"USD\",\n \"text\": \"$6.66\",\n \"value\": \"6.66\"\n },\n \"tax_amount\": {\n \"currency\": \"USD\",\n \"text\": \"$0.00\",\n \"value\": \"0.00\"\n },\n \"title\": null,\n \"total\": {\n \"currency\": \"USD\",\n \"text\": \"$-23.34\",\n \"value\": \"-23.34\"\n },\n \"total_paid\": {\n \"currency\": \"USD\",\n \"text\": \"$0.00\",\n \"value\": \"0.00\"\n },\n \"updated_at\": \"2020-06-04T16:49:18+0000\"\n }\n }\n }\n ]\n }\nThis describes the use cases for processing Invoice events. These events are wrapped in an invoice key.
Valid values for the status fields are:
draftbalance_outstanding (when this is 0 the invoice is fully paid)These events will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": \"a9ce6d53-dc32-51f8-81b4-3a00f47c5bdf\",\n \"Put\": {\n \"invoice\": {\n \"description\": null,\n \"discount_amount\": {\n \"currency\": \"USD\",\n \"text\": \"$30.00\",\n \"value\": \"30.00\"\n },\n \"discount_percent\": null,\n \"doc_type\": \"Estimate\",\n \"external_id\": \"your_estimate_id\",\n \"id\": 4697,\n \"job\": {\n \"external_id\": \"your_enterprise_id\"\n },\n \"job_id\": 383147,\n \"lines\": [\n {\n \"billing_item_id\": null,\n \"id\": \"d9d0016b-554b-4748-9b00-0cf6aa7ff02c\",\n \"billing_item\": {\n \"external_id\": \"your_catalog_id\"\n }\n \"markup\": 0,\n \"price\": {\n \"currency\": \"USD\",\n \"text\": \"$3.33\",\n \"value\": \"3.33\"\n },\n \"price_with_markup\": {\n \"currency\": \"USD\",\n \"text\": \"$3.33\",\n \"value\": \"3.33\"\n },\n \"qty\": 2,\n \"taxable\": true,\n \"title\": \"\",\n \"total\": {\n \"currency\": \"USD\",\n \"text\": \"$6.66\",\n \"value\": \"6.66\"\n }\n }\n ],\n \"number\": \"1005\",\n \"paid\": false,\n \"po_number\": \"asfdfdasdf\",\n \"status\": \"draft\",\n \"subtotal\": {\n \"currency\": \"USD\",\n \"text\": \"$6.66\",\n \"value\": \"6.66\"\n },\n \"tax_amount\": {\n \"currency\": \"USD\",\n \"text\": \"$0.00\",\n \"value\": \"0.00\"\n },\n \"title\": null,\n \"total\": {\n \"currency\": \"USD\",\n \"text\": \"$-23.34\",\n \"value\": \"-23.34\"\n },\n \"total_paid\": {\n \"currency\": \"USD\",\n \"text\": \"$0.00\",\n \"value\": \"0.00\"\n },\n \"updated_at\": \"2020-06-04T16:49:18+0000\"\n }\n }\n }\n ]\n }\nThis describes the use cases for processing Payment events. These events are wrapped in an payment key.
These events will have the following payload structure:
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": \"884a38c7-087c-5d50-a1e6-6f943c18bd7b\",\n \"Put\": {\n \"payment\": {\n \"amount\": {\n \"currency\": \"USD\",\n \"text\": \"$1.11\",\n \"value\": \"1.11\"\n },\n \"billing_document_id\": 4699,\n \"billing_document\": {\n \"external_id\": \"your_external_id\"\n },\n \"card_name\": null,\n \"card_number\": null,\n \"card_type\": null,\n \"id\": 514,\n \"payment_method\": \"check\",\n \"reference\": null,\n \"result\": \"success\",\n \"transaction_id\": \"xxxx\",\n \"updated_at\": \"2020-06-04T17:40:52+0000\"\n }\n }\n }\n ]\n }\n }\nThis section is only relevant if you are integrating with Dispatch's billing model
\nThese are the typical API calls you will need to make to process billing requests to the Dispatch platform.
\nIn Dispatch we refer to both Estimates and Invoices as Billing Documents. This is because Estimates and Invoices are two sides of the same coin and are structurely very similar. We differentiate between them use the doc_type attribute on the Billing Document.
A Billing Document consists of a header and details section:
\nproduct or service that you are selling and every line item must be linked to a master \"billing item\".To illustrate the difference between a line item and billing item consider the following:
\nThe typical flow for billing documents is as follows:
\nThis describes the use cases for processing Calendar Event events. These events are wrapped in an calendar_event element.
These events will have the following payload structure:
\n {\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": null,\n \"Put\": {\n \"calendar_event\": {\n \"uuid\" : \"317133c0-1a9d-41c9-a548-08bddabdf79\",\n \"title\": \"Event title\",\n \"started_at\" : \"2019-10-21T08:30:00Z\",\n \"completed_at\": \"2019-10-21T09:30:00Z\",\n \"external_id\": \"your_id\"\n }\n }\n }\n ]\n }\n }\nThis section is only relevant if you wish to consume updates for Calendar Events
\n","event":[{"listen":"prerequest","script":{"id":"7f282b0f-a36e-4ad9-981d-888729fbd620","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"7fdfe78e-d992-4928-84cb-a3b70f24d401","type":"text/javascript","exec":[""]}}],"_postman_id":"ebfaf899-0b21-4f7f-915b-5c29cfc6670e"},{"name":"Custom Forms","item":[{"name":"Custom Form","id":"382b29f3-8f96-42ed-89c2-10e72a485635","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"formdata","formdata":[]},"url":"https://connect-sbx.dispatch.me/agent/out","description":"This describes the use cases for processing Custom Form events. These events are wrapped in an customForm element.
Use the form_name to determine which custom form data this is for.
These events will have the following payload structure (this example is incomplete):
\n \"Payload\": {\n \"Actions\": [\n {\n \"ID\": \"some_id\",\n \"Put\": {\n \"customform\": {\n \"form_data\": {\n \"cash_amount\": \"1222\",\n \"mileage\": \"1232\"\n },\n \"form_name\": \"wfm_custom_form_close_out\",\n \"job\": {\n \"external_id\": \"your_id\"\n },\n \"job_id\": 383147\n }\n }\n }\n ]\n }\n\nCustom forms are used to gather additional data from the field. One or more custom forms can be defined and the information gathered can be sent back when submitted.
\n","event":[{"listen":"prerequest","script":{"id":"7f485883-a546-48ce-9189-caeab4213903","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"137c9d46-04e5-4731-8167-8fdfbd82ef8a","type":"text/javascript","exec":[""]}}],"_postman_id":"e565b74d-9319-4feb-aeb7-b052c924e9d3"},{"name":"Rendering Images","item":[{"name":"Get File","id":"f3f11bce-b781-4713-a09d-e8b8628fa9f7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://files-api-sandbox.dispatch.me/v1/datafiles/{{file_token}}/{{format}}","description":"Request
\nwhere:
\nfile_token - that you obtained from Dispatchformat - this tells the API how to render the file. Valid values are:Response
\nThe file in the format you specified. You will need to look at the Content-Type header in order to know how to render the file. This will contain the mime type.
See this python example for working with files.
\n","urlObject":{"protocol":"https","path":["v1","datafiles","{{file_token}}","{{format}}"],"host":["files-api-sandbox","dispatch","me"],"query":[],"variable":[]}},"response":[{"id":"125a4fb7-88b8-4dee-ac3d-5bc1add11deb","name":"Sample Response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","enabled":true,"description":"The mime type of this content"}],"url":"https://files-{{server}}.dispatch.me/v1/datafiles/{{file_token}}/square_50"},"status":"OK","code":200,"_postman_previewlanguage":"html","header":[{"name":"Accept-Ranges","key":"Accept-Ranges","value":"bytes","description":""},{"name":"Cache-Control","key":"Cache-Control","value":"max-age=315576000","description":""},{"name":"Content-Encoding","key":"Content-Encoding","value":"","description":""},{"name":"Content-Length","key":"Content-Length","value":"1567","description":""},{"name":"Content-Type","key":"Content-Type","value":"image/jpeg","description":""},{"name":"Date","key":"Date","value":"Thu, 21 Apr 2016 12:27:31 GMT","description":""},{"name":"ETag","key":"ETag","value":"\"789baa92be25f5607b053402bc88f6d2\"","description":""},{"name":"Last-Modified","key":"Last-Modified","value":"Thu, 21 Apr 2016 12:27:13 GMT","description":""},{"name":"Server","key":"Server","value":"AmazonS3","description":""},{"name":"x-amz-id-2","key":"x-amz-id-2","value":"vRD1qTjm55cG3piNZNQAdQL8oHe9hEULUqIGPd+GUts+wbanVWB4V8gmuzTgVD+6GBWrNRniecA=","description":""},{"name":"x-amz-request-id","key":"x-amz-request-id","value":"E0F998ADA0809811","description":""}],"cookie":[],"responseTime":null,"body":""},{"id":"7860978f-1424-491e-8f2d-1d59ec9f301d","name":"Example Response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","enabled":true,"description":"The mime type of this content"},{"key":"Accept","value":"application/json","enabled":true},{"key":"Authorization","value":"Bearer 5a1c04b962cfd5971f2b23f00ce8481d4c9fce5ead7beaa5878dc90c3a0050e9","enabled":true},{"key":"Cache-Control","name":"Cache-Control","value":"no-cache"},{"key":"Postman-Token","name":"Postman-Token","value":"5d3933de-b936-101c-69be-d394fd070e71"}],"url":{"raw":"https://api-sandbox.dispatch.me/v1/organizations?filter[by_external_ids][]=JOJ001","protocol":"https","host":["api-sandbox","dispatch","me"],"path":["v1","organizations"],"query":[{"key":"filter[by_external_ids][]","value":"JOJ001"}]}},"status":"OK","code":200,"_postman_previewlanguage":"javascript","header":[{"name":"Cache-Control","key":"Cache-Control","value":"max-age=0, private, must-revalidate","description":""},{"name":"Connection","key":"Connection","value":"keep-alive","description":""},{"name":"Content-Encoding","key":"Content-Encoding","value":"gzip","description":""},{"name":"Content-Type","key":"Content-Type","value":"application/json; charset=utf-8","description":""},{"name":"Date","key":"Date","value":"Wed, 16 Mar 2016 18:31:14 GMT","description":""},{"name":"Server","key":"Server","value":"nginx","description":""},{"name":"Transfer-Encoding","key":"Transfer-Encoding","value":"chunked","description":""},{"name":"Vary","key":"Vary","value":"Accept-Encoding, Origin","description":""},{"name":"X-Content-Type-Options","key":"X-Content-Type-Options","value":"nosniff","description":""},{"name":"X-Frame-Options","key":"X-Frame-Options","value":"SAMEORIGIN","description":""},{"name":"X-Request-Id","key":"X-Request-Id","value":"477baf2d-dd55-4d5c-92dd-f2232842944f","description":""},{"name":"X-Runtime","key":"X-Runtime","value":"0.026263","description":""},{"name":"X-XSS-Protection","key":"X-XSS-Protection","value":"1; mode=block","description":""}],"cookie":[],"responseTime":null,"body":"{\"organizations\":[{\"id\":469,\"created_at\":\"2016-03-03T15:47:55+0000\",\"updated_at\":\"2016-03-15T15:52:16+0000\",\"name\":\"Joe's Plumbing\",\"email\":\"devs+joj001@dispatch.me\",\"email_from\":null,\"phone_number\":\"+15559626103\",\"twilio_phone_number\":null,\"line_item_level_tax\":false,\"logo_token\":null,\"tracker_logo_token\":null,\"url\":null,\"about\":null,\"accepted_payment_options\":[\"cash\",\"check\"],\"is_configured\":false,\"working_hours\":{\"0\":[],\"1\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"2\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"3\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"4\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"5\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"6\":[]},\"service_types\":{},\"is_allowed_notifications\":true,\"is_available_for_job_offers\":true,\"timezone\":null,\"country\":\"United States\",\"currency\":\"USD\",\"signup_source\":\"cchs\",\"reporting_enabled\":true,\"max_job_drive_time\":0,\"auto_generate_service_fee_invoice\":false,\"version\":\"v1\",\"updated_by\":\"account:c138f261-6d5b-4fc2-ac5b-ddef29d01470\",\"external_ids\":[\"demo:JOJ001\",\"demo:test_add1\",\"demo:test_add2\"],\"address\":null}]}"},{"id":"d581124d-430d-4620-88ce-ca9ffefa9c51","name":"Example Response","originalRequest":{"method":"GET","header":[{"key":"Content-Type","value":"application/json","enabled":true,"description":"The mime type of this content"},{"key":"Accept","value":"application/json","enabled":true},{"key":"Authorization","value":"Bearer 5a1c04b962cfd5971f2b23f00ce8481d4c9fce5ead7beaa5878dc90c3a0050e9","enabled":true},{"key":"Cache-Control","name":"Cache-Control","value":"no-cache"},{"key":"Postman-Token","name":"Postman-Token","value":"5d3933de-b936-101c-69be-d394fd070e71"}],"url":{"raw":"https://api-sandbox.dispatch.me/v1/organizations?filter[by_external_ids][]=JOJ001","protocol":"https","host":["api-sandbox","dispatch","me"],"path":["v1","organizations"],"query":[{"key":"filter[by_external_ids][]","value":"JOJ001"}]}},"status":"OK","code":200,"_postman_previewlanguage":"javascript","header":[{"name":"Cache-Control","key":"Cache-Control","value":"max-age=0, private, must-revalidate","description":""},{"name":"Connection","key":"Connection","value":"keep-alive","description":""},{"name":"Content-Encoding","key":"Content-Encoding","value":"gzip","description":""},{"name":"Content-Type","key":"Content-Type","value":"application/json; charset=utf-8","description":""},{"name":"Date","key":"Date","value":"Wed, 16 Mar 2016 18:31:14 GMT","description":""},{"name":"Server","key":"Server","value":"nginx","description":""},{"name":"Transfer-Encoding","key":"Transfer-Encoding","value":"chunked","description":""},{"name":"Vary","key":"Vary","value":"Accept-Encoding, Origin","description":""},{"name":"X-Content-Type-Options","key":"X-Content-Type-Options","value":"nosniff","description":""},{"name":"X-Frame-Options","key":"X-Frame-Options","value":"SAMEORIGIN","description":""},{"name":"X-Request-Id","key":"X-Request-Id","value":"477baf2d-dd55-4d5c-92dd-f2232842944f","description":""},{"name":"X-Runtime","key":"X-Runtime","value":"0.026263","description":""},{"name":"X-XSS-Protection","key":"X-XSS-Protection","value":"1; mode=block","description":""}],"cookie":[],"responseTime":null,"body":"{\"organizations\":[{\"id\":469,\"created_at\":\"2016-03-03T15:47:55+0000\",\"updated_at\":\"2016-03-15T15:52:16+0000\",\"name\":\"Joe's Plumbing\",\"email\":\"devs+joj001@dispatch.me\",\"email_from\":null,\"phone_number\":\"+15559626103\",\"twilio_phone_number\":null,\"line_item_level_tax\":false,\"logo_token\":null,\"tracker_logo_token\":null,\"url\":null,\"about\":null,\"accepted_payment_options\":[\"cash\",\"check\"],\"is_configured\":false,\"working_hours\":{\"0\":[],\"1\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"2\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"3\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"4\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"5\":[\"08:00:00 - 11:59:59\",\"12:00:00 - 15:59:59\"],\"6\":[]},\"service_types\":{},\"is_allowed_notifications\":true,\"is_available_for_job_offers\":true,\"timezone\":null,\"country\":\"United States\",\"currency\":\"USD\",\"signup_source\":\"cchs\",\"reporting_enabled\":true,\"max_job_drive_time\":0,\"auto_generate_service_fee_invoice\":false,\"version\":\"v1\",\"updated_by\":\"account:c138f261-6d5b-4fc2-ac5b-ddef29d01470\",\"external_ids\":[\"demo:JOJ001\",\"demo:test_add1\",\"demo:test_add2\"],\"address\":null}]}"}],"_postman_id":"f3f11bce-b781-4713-a09d-e8b8628fa9f7"}],"id":"69e45945-4c05-4702-a5e9-fc0fd625b428","description":"See this python sample
\n","event":[{"listen":"prerequest","script":{"id":"7935511b-5009-4dcf-ad53-a80b31fd94f8","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"cf8f4f57-b045-49b5-a06d-8044ac6d4899","type":"text/javascript","exec":[""]}}],"_postman_id":"69e45945-4c05-4702-a5e9-fc0fd625b428"},{"name":"Availability","item":[{"name":"Whitespace","id":"783107dd-0dcc-4095-aa6f-e9ba90cf2a10","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{token}}"}],"url":"https://api-sandbox.dispatch.me/v1/availability/slots?user_external_id[]=a013900001Zc9FkAAJ&user_external_id[]=a013900001aPXO1AAO&start_time=2022-10-24T04:00:00Z&end_time=2022-10-25T03:59:59Z&duration=60","description":"Also see Match Technicians for a more general purpose approach for matching technicians to a given job.
\nThe whitespace API looks at the technician schedules and returns slots that have enough availability for the estimated appointment duration passed in.
\nSo for example, given an appointment of 1 hour duration and the following schedule for these two techs on Oct 24:
\nIt will return 4 slots (see sample response) - each of these slots contain enough time for the appointment.
\nURL Parameters:
\nThis returns the inverse of the whitespace API. So while the whitespace shows all of the available slots, this API returns:
\nSo assuming this schedule:
\nThe response (see example) returns:
\nday_start and day_end indicated by the section highlighted in yellowURL Parameters:
\nThe results returned by Match Technicians is similar to that returned by the whitespace API in that it returns a list of users that have the availability to work the appointment.
\nHowever with this API, you pass in an address (along with some other parameters) and the API will determine which users can perform the job based on proximity (and other factors).
\nURL Parameters:
\nThis API returns orgs (providers/vendors) that match the criteria input. For example, if you pass in a zip code of 80207 it returns the list of orgs that service this zip code.
Additional match parameters for match are supported however not yet updated in this documentation.
\n","urlObject":{"protocol":"https","path":["v3","search","oms"],"host":["api-sandbox","dispatch","me"],"query":[{"key":"postal_code","value":"80207"}],"variable":[]}},"response":[{"id":"5d86973f-8f22-41ba-904c-342d1e14208e","name":"Match Orgs","originalRequest":{"method":"GET","header":[{"key":"Authorization","value":"Bearer {{token}}","type":"text"}],"url":{"raw":"http://api.dispatch.me/v3/search/oms?postal_code=80207","protocol":"http","host":["api","dispatch","me"],"path":["v3","search","oms"],"query":[{"key":"postal_code","value":"80207"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Sun, 12 Feb 2023 13:49:17 GMT"},{"key":"Content-Type","value":"application/json; charset=utf-8"},{"key":"Content-Length","value":"1640"},{"key":"Connection","value":"keep-alive"},{"key":"Access-Control-Allow-Credentials","value":"true"},{"key":"Access-Control-Allow-Headers","value":"Origin, Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, X-Transaction-ID, X-Analytics-Tags, Analytics-Client-Id, X-Account-ID, X-API-Version, Client-Id"},{"key":"Access-Control-Allow-Methods","value":"DELETE, GET, HEAD, OPTIONS, PATCH, POST, PUT"},{"key":"Access-Control-Allow-Origin","value":"*"},{"key":"Access-Control-Expose-Headers","value":"Content-Length"},{"key":"Access-Control-Max-Age","value":"86400"}],"cookie":[],"responseTime":null,"body":"{\n \"account_organizations\": [\n {\n \"organization_id\": 200383,\n \"external_ids\": [\"org_external_id\"]\n }\n ]\n}"}],"_postman_id":"7e79741c-3c7f-48fe-bb3c-60d8989fe377"}],"id":"d184cc9a-674a-44ad-ab40-1858ec734225","description":"The availability APIs are by definition real time and therefore need to use the oauth authentication method.
\nPlease request oauth keys from Dispatch if you don't already have them.
\nThe following APIs can be used to determine availability
\nChoosing which one to use is at your discretion depending on what better suits your requirement.
\nAll APIs take into account the following to determine availability:
\nMessages will have the following format. The sender will either be customer (sent from customer) or organization sent from provider.
{\n \"Type\": \"inbox_message\",\n \"Payload\": {\n \"Data\": {\n \"external_customer_id\": \"1850562-10797934\",\n \"external_organization_id\": \"9229ADAM\",\n \"sender\": \"customer\",\n \"message_content\": \"Stop texting me!!\"\n }\n }\n}\n\nEvery payload that you pick up from the agent/out endpoint will include the following payload wrapper. The details inside the Payload key will contain the relevant updates for your system. The wrapper elements - specifically ProcedureIDand Receipt are used to mark the payload as having been received and will remove the payload from the queue. The technical steps for doing so are best illustrated in the outbound code samples.
[\n {\n \"Message\": {\n \"Request\": {\n \"ProcedureID\": \"b332b621-f7ef-405d-8075-7332aef9bba7\",\n \"Type\": \"some_type\",\n \"Payload\": {\n \"some_payload\": \"either the canonical described in this document or an agreed upon custom format\"\n }\n },\n \"ID\": \"ed172c8b-aba0-4f1b-b477-6dc9c487fcbd\",\n \"Receipt\": \"AQEBQ4Uw8YrVICgfZjXqtQhK6/PBodouACu8J4P0z27ysnHLTi7rC0r7cueMFnq9CuDpG6lXtCTKdXrjjrUM0GTi3PCY/tjCAd8uC77KN3tTLGFwiSKRUHoni4wLqRjyvNYnJFv2Y1sHn8DSgSIzB8kx5Zv6krK17jvzwhxom0+nM5g99iuavW+TtrDdnQVwc5lPw5/q+AuxSVzkWQS3eyP1AVXpXUpRUuDutvPggo8890HPPO6p+BfPZ1STxB1bN62PXuRRgG1RMu+O3vfP78kGR+DWkJSUr4kDuX3LLhztNtTgyPY6BQbcF7SZBMNExGkf+B1LbUlDmXtd33U5QjAXzw==\"\n }\n }\n]\nThe following conventions apply to all event processing:
\nexternal_id - This is the Enterprise's record IDupdated_at - Use this to mark the time the event occuredThe structures defined in this section are our default. If you already have your own preferred structure and/or format in which you prefer to receive the data, please let us know - there's a good chance we'll be able to accomodate you.
\nPlease be aware that we may put additional events in the stream as our product evolves. Although we will not change the names of attributes in the payload, it is possible that we'll add new attributes to the payload. Therefore make sure that your payload consumption will not break if a new attribute starts being included.
\nEach time you poll the agent/out endpoint you should pull down using a maxNumberOfMessages of 10 (this is currently the highest number of messages you can request at a time). If the messages returned is equal to maxNumberOfMesssages you should poll again. Repeat until the queue is empty. In this way, you will clear out the queue each time you poll which ensures that your updates will be timely and the queue will remain low. The code samples incorporate this logic in them - be sure to follow this guidance!
Make sure to \"ack\" each message directly after downloading it. That is, you should NOT poll for 10 messages, process them all and then ack each message. Instead you should poll for 10 messages, process the first and then ack it, process the second and ack it and so on. This is important because there is an expiration (typically 30 seconds) to ack a polled message and if you do it after that time, the ack will be rejected and the message will stay in the queue until you poll it again. Again the code samples incorporate this logic in them, so if you follow the pattern shown you'll be in good shape.
\nSeparate polling the endpoint from the business logic to update your business system. Often business logic (including multiple API interplay steps) can be involved and slow the system down. You should instead download the messages into a local store (e.g. sql table) and \"ack\" immediately after which lets us know that you received the message. From there you can process into your business systems as necessary. Needless to say, if you process directly to your business system and that takes \"too long\", you will run into the expiration issue mentioned above.
\nOnly have a single process that polls the endpoint. If you have multiple processes polling the endpoint they can interfere with one another (as SQS makes messages invisible to other processes from the process being polled in order to prevent a message from being processed more than once). If you wish to employ multiple processes to poll the endpoint, then you should ensure that they are timed to alternate with one another and you should reach out Dispatch as we may need to tune the queue based on your polling strategy.
\nIf for some reason you get an exception while locally storing a message, do not ack the message. If you do, the message will disappear from the queue and there will be data loss. By not acking it, you are ensuring that the message remains on the queue for processing the next time you poll. However, please be aware that if you are repeatedly getting exceptions while locally storing a message, the queue will grow and will block processing due to the FIFO nature of the queue. Therefore you should be sure to research this event should it occur to prevent a backlog (which will have the affect of delaying the timely processing of messages sent from Dispatch)
\nThe sections above describe the \"Quick Start\" connector integration scenarios.
\nBeyond that, there may be other scenarios for your use case. The intention of this section is to document these. Please note that this section will use the API canonical format for documenting inbound and outbound requests. However, as mentioned in other sections of this document, we are not limited to that and if you have a format for integration that is more native to your platform - that is not a problem. Just describe those to us and we'll work on mapping them to/from the Dispatch Platform.
\n","event":[{"listen":"prerequest","script":{"id":"f3187ada-257c-4d30-b112-bd5e56959f98","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"bfe58c9c-de01-4765-a4e7-381457b10d4b","type":"text/javascript","exec":[""]}}],"_postman_id":"39c4cc81-2e84-487d-b1f4-a3e98204916d"}],"event":[{"listen":"prerequest","script":{"id":"17ea7d55-6ce5-46a9-97fe-8c077f5076e1","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"6d43753b-2e7c-4452-98de-0d65efb3a44a","type":"text/javascript","exec":[""]}}]}