Booking an Appointment using the API

The API to use to book an Appointment is POST /{instance}/book/.

This API endpoint is combination of the following other endpoints:

POST /{instance}/customers, POST /{instance}/jobs and POST /{instance}/appointments

This aggregate allows:

1. Creating a new Customer.
2. Creating new Job.
3. Creating the first Appointment.
4. Scheduling the first Appointment. (optional)
5. Completing Job/Customer questions (optional).

The payload combines Customer Details a Property Address, Job Settings, Booking Question Answers and Schedule information.

Customer Details

We will begin with Customer Details fields of the payload.

{
  "customerAgentId": 0,
  "title": "string",
  "firstname": "string",
  "surname": "string",
  "areaCode": "string",
  "homePhone": "string",
  "mobilePhone": "string",
  "consentToSMS": "EC",
  "customerRef": "string",
  "email": "string",
  "companyName": "string",
  "customerType": "B",
  "gstRegistered": true,
  "taxId": "string",

}

For a Residential Customer Details a payload may look like:

{
  "customerAgentId": 1, 
  "firstname": "Bob",
  "surname": "Smith",
  "mobilePhone": "0404555555",
  "consentToSMS": "IC",
  "customerRef": "MYSalesForceID",
  "email": "test@dataforce.com.au",
  "customerType": "R"
  
}

For a Business Customer Details a payload may look like:

{
  "customerAgentId": 1, 
  "firstname": "Company",
  "surname": "Director",
  "homePhone": "1300336729",
  "mobilePhone": "04045555555",
  "consentToSMS": "EC",
  "customerRef": "MYSalesForceID",
  "email": "test@dataforce.com.au",
  "companyName": "Dataforce Services",
  "customerType": "B",
  "gstRegistered": true,
  "taxId": "26141841849", // 11 Characters e.g ABN/ACN 
  
}

The taxId has maximum of 11 characters we expect either an ABN (Austrian Business Number) or ACN (Australia Company Number).

Mandatory Fields and Program Preferences

ASAP has configuration options under Program Preferences > Customer tab:

1. Make customer title field mandatory.
2. Make customer firstname mandatory.
3. Require customer email address.
4. Allow null External Customer Ref.
5. Allow only numbers in External Customer Ref.

Please keep these in mind when building the customer payload.

Agent and Fieldworker Access

With regards to customerAgentId or later agentId or fieldworkerId, access is decided by the Role granted to API key.

For Example after creating API key if its assigned a role e.g Global Administrator.

and if the Role has ‘Access All Agents’ checked,

this API Key can choose any Agent or Fieldworker from the Register.

If the Role is missing ‘Access All’ the Key is restricted to Agents where access has been specially granted in the ‘User profile’.

Address Details

To create a booking a customer must have a property address.

We recommend you use an address verification service to fix partial and vanity addresses before submitting to ASAP.

An Address has the following fields in its payload:

{
  "buildingName": "",
  "levelNo": "",
  "lotNo": "",
  "unitNo": "404",
  "unitType": "UNIT",
  "streetNo": "33",
  "streetName": "Lexington",
  "streetType": "DRIVE",
  "streetTypeSuffix": "",
  "suburb": "Bella Vista",
  "postCode": 2153,
  "state": "NSW",
  "allowDuplicateAddress": true
}

The required fields in an Address are, streetName, suburb, postCode, state a streetNo or lotNo.

The following fields have fixed values use data-dictionary endpoints below:

For example if you submit an address with incorrect streetType the API will return a validation error like below:

ASAP maintains a database of valid suburb and postcode combinations you MUST use one of these combinations to create a booking.

API will return validation errors if an invalid combination is used:

The property allowDuplicateAddress can prevent duplicate customers being created if they have the same property address the API will return a validation error like below:

Job Settings

This section of the booking request relates to Job properties.

{
  "creationDate": "2024-11-25T02:22:58.127Z",
  "agentId": 0,
  "clientId": 0,
  "sourceId": 0,
  "sourceAssociateId": 0,
  "trackingCode": "string",
  "salesPipelineStageId": 0,
} 

The property creationDate if not provided will default to current date and may be used to ‘back date’ Job creation.

The following endpoints can be used to populate Job properties:

The property agentId is MANDATORY use the endpoint above for a list of agentsId and used to manage Job access.

The property clientId is MANDATORY a client is used to represent an aggregation partner who buy the certificates. Use the endpoint above for a list of clients.

Both sourceId and sourceAssociateId are optional and are used to track the source of the lead, use the two endpoints above for a full list.

The salesPipelineStageId relates to ASAP pre job sales module and is optional, use the endpoint above for a list of agentsId.

The trackingCode allows for an adhoc identifier less than 100 characters, the code can be used in search API requests.

A minimum payload may look like the below:

{
"agentId": 1,
"clientId": 1,
"trackingCode": "AUniqueJobTrack"
}

Schedule/Appointment Details.

The following section is for details of the Appointment.

{
  "workTypeId": 0,
  "jobInstruction": "string",
  "hazardCodeId": 0
}

The following endpoints can be used:

The workTypeId selected during creation must not be a child of another for example Commercial Lighting activity you could book either a ‘CLU Assessment’ or ‘CLU Install (All-in-one)’ but you can not create a ‘CLU Install’ as that work type is child of the Assessment.

The property hazardCodeId is optional and is used to categorize safety hazards (they must be defined in backend).

The jobInstruction property is short message (less than 2000 characters) for the fieldworker and is shown both in Runabout and Backends Job Correspondences.

If this payload was submitted the API would create a NEW Customer/Job/Appointment but leave the Appointment in Waiting status ready to be scheduled by an Operator.

If its necessary to choose a date/time include the following properties, must include a Fieldworker:

{
"fieldworkerId": 100,
"activityDate": "2024-11-25T03:40:12.203Z",
"commencementDate": "2024-11-25T03:40:12.203Z",
"scheduledDate": "2024-11-25T03:40:12.203Z",
"duration": 60
}

To see list of fieldworkers the endpoint *GET** /{instance}/fieldworkers will list those in the Register the API key has access too.

The property activityDate and commencementDate are optional and will be assigned with current date if not supplied.

The duration property is length of the Appointment in Minutes e.g 30,60,90,120.

The scheduledDate date and time when a fieldworker attends the site.

Common Errors during scheduling

The selected fieldworker must have access to suburb/postcode combination used in the customers property address. The API may return validation error like below if their are access issues or a wrong id:

If the Worktype does not exist or has been disabled the API will return a validation error.

Job/Customer Question answers.

Job and Customer questions can be included in this Booking payload.

{
"blockAnswers": [
    {
      "questionBlockTypeId": 0,
      "blocks": [
        {
          "answers": [
            {
              "questionId": 0
            }
          ]
        }
      ]
    }
  ],
  "answers": [
    {
      "questionId": 0
    }
  ]

}

We covered using a similar payload in Save Appointment Question using the API the Booking payload is restricted to Job and Customer questions only and If Appointment Questions are needed use a 2nd API request to endpoints in the linked article.

Successful Creation

If we try a payload (without any Job Questions).

{
  "customerAgentId": 1, 
  "firstname": "Bob",
  "surname": "Smith",
  "mobilePhone": "0404555555",
  "consentToSMS": "IC",
  "customerRef": "MYSalesForceID",
  "email": "test@dataforce.com.au",
  "customerType": "R",
  "buildingName": "",
  "levelNo": "",
  "lotNo": "",
  "unitNo": "404",
  "unitType": "UNIT",
  "streetNo": "33",
  "streetName": "Lexington",
  "streetType": "DRIVE",
  "streetTypeSuffix": "",
  "suburb": "Bella Vista",
  "postCode": 2153,
  "state": "NSW",
  "allowDuplicateAddress": true,
  "agentId": 1,
  "clientId": 1,
  "trackingCode": "AUniqueJobTrack",
  "workTypeId": 4,
  "jobInstruction":"Knock on Door three times",
  "fieldworkerId": 718,
  "scheduledDate": "2024-11-25T03:40:12.203Z",
  "duration": 60
}

The Job/Appointment and Customer ids will be returned if the booking is successful.