Retrieving Appointment Data - V4 Appointments API

Retrieving Appointment Data - V4 Appointments API

The following should be enough information to allow appointments to be created, modified, deleted, and retrieved through the API and is correct as of the date the article was written.

Company Controller

Retrieving Branch ID
A number of end points require the branch ID to retrieve data. The end point to retrieve the branch is located in the Company Controller in the following end points.

/v4/appointments/{shortName}/company/branches/{offset}/{count}

Please note, the branch ID field will appear as OID. The primary object ID will always appear as OID in each response. We cannot obtain the branch ID on your behalf. You will need to retain the value of the OID for the branch you will want to search against in any other endpoints.

Diary Controller

Retrieving allocation slots

/v4/appointments/{shortName}/diary/appointmenttypes/allocations/{offset}/{count}

• This endpoint provides a list of available appointment slots for the next 7 days starting from the preferred date.
• An allocated appointment slot is necessary for creating a diary appointment.
• Appointment slots must be set up in AgentOS by a user, as this cannot be done via the API.
• An appointment type ID is required for this process. Retrieving appointment Type ID

Retrieving Appointment Types

/v4/appointments/{shortName}/diary/appointmenttypes/{offset}/{count}

• This endpoint allows you to fetch all appointment types for a company.

Retrieving Appointments
You can retrieve appointments in a number of ways, via branch, recurring appointments or by appointment ID.
Retrieve appointments by appointment type

/v4/appointments/{shortName}/diary/appointments/{branchID}/{offset}/{count}

• You can retrieve appointments using the appointment type and branch ID.
• The endpoint supports multiple appointment types.
• A date range (startDate and endDate) must be specified.

Retrieve all recurring appointments

/v4/appointments/{shortName}/diary/recurringappointment

• This endpoint fetches all recurring appointments.
• Both the appointment Type ID and branch ID are required for a successful call.Retrieve appointment by Appointment ID

Retrieving Appointment by Appointment ID

/v4/appointments/{shortName}/diary/appointment/{appointmentID}

• Once you have an appointment ID, you can use this endpoint to get detailed information about that specific appointment.

Creating an appointment

/v4/appointments/{shortName}/diary

• This endpoint allows you to create an appointment by posting it into a valid diary allocation.
• A valid diary allocation is necessary and can be obtained as mentioned earlier.
• Required parameters include the Property ID (from Lettings or Sales Controller) and the appointment details submission model.
• If the Guest ID is not provided, a new lettings prospect or applicant buyer will be created.
• Staff ID and Appointment Type ID are also required.

{
"AllocationDetails": {
"Start": "2024-07-09T10:13:52.590Z",
"End": "2024-07-09T10:13:52.590Z",
"StaffName": "string",
"StaffID": "string"
},
"AppointmentType": "string",
"Subject": "string",
"ExtraComments": "string",
"Guests": [
{
"OID": "string",
"Forename": "string",
"Surname": "string",
"MobilePhone": "string",
"EmailAddress": "string",
"AllowMarketingCorrespondence": true
}
]
}
Update Existing Appointment

/v4/appointments/{shortName}/appointment/update

• You'll need the appointment ID, which can be found when retrieving appointments.
• The appointment details model must be populated similar to when creating an appointment.
• Staff ID, Appointment Type ID, and a valid allocation slot are necessary before modifying an existing appointment.
• To update an appointment to a different property, the current appointment must be deleted and a new one created.

Post Feedback for a Property

/v4/appointments/{shortName}/diary/feedback

• This endpoint is currently for posting feedback on Lettings Properties.
• Future updates will expand this to include sales instructions.
• The appointment ID, Property ID, and feedback are required.

Modify the cancellation status of a diary appointment.

/v4/appointments/{shortName}/diary/cancelationStatus/{cancelationStatus}

·       You'll need the appointment ID and the desired cancellation status (true or false).

·       This action changes the cancellation status but does not remove the appointment.

Contacts Controller

Match Guest Parameters with an existing person

/v4/appointments/{shortName}/contacts/guest/match/{offset}/{count}

• This endpoint allows you to input parameters to retrieve a person ID.
• Required information includes the person's email address, branchID, forename, and surname.

Retrieve all staff members for a branch

/v4/appointments/{shortName}/contacts/staff/{offset}/{count}

·       This endpoint provides a list of all staff members for a specified branch.

·       You can obtain staff member IDs, which are useful for creating or modifying appointments.

Lettings Controller

Retrieve advertise tenancies set up in the system

/v4/appointments/{shortName}/lettings/tenancies/advertised/{offset}/{count}

• This endpoint allows you to fetch advertised tenancies established for the company.
• It's used to obtain the Property ID, which is labeled as 'PropertyOID' in the response.

Sales Controller

Retrieve advertised Sales Instructions set up on the system

/v4/appointments/{shortName}/sales/instructions/advertised/{offset}/{count}

• This endpoint provides access to advertised sales instructions set up for the company.
• It's used to obtain the Sales Instruction ID, which is labeled as 'OID' in the response.

Messaging Controller

/v4/appointments/{shortName}/messaging/{branchID}

• This endpoint facilitates sending emails through a specific branch.
• You'll need to provide the branch ID (obtainable as mentioned earlier) and the email submission model.
• CC and BCC fields in the email submission are optional

"Subject": "string",
"Content": "string",
"To": [
"string"
],
"CC": [
"string"
],
"BCC": [
"string"
]
}