Invitations

Owned by Joel Morgan Kearney (Unlicensed)
Last updated: Aug 19, 2024 by Andrew Forster
11 min read

The Invitations API is used to access and modify the invitation objects and invitationCampaign objects on your business' account. The Invitations API is connected to the Locations, Staff, and Services APIs, as invitation campaigns are sent out for events at a particular location with a particular staff member for a particular service.


On this page




Invitations API Endpoints

Return to Top

These are the endpoints that are available under the /invitations path, which lists all the different gift cards on your business' account.

EndpointDescription
GET /invitation/{invitationUUId}Returns a JSON object for the specified invitation.
GET /invitation/invitationCampaign/{invitationCampaignId}Returns a JSON object for the specified invitationCampaign.
GET /invitationCampaignReturns all invitationCampaign objects on a business' account in array format.
GET /invitationCampaign/{invitationCampaignId}Returns all invitation objects for specified invitationCampaign.
POST /invitationCampaign/client/{clientIdList}

Sends an email invitation to specified clients.

Request body/payload: Must pass an invitation campaign object in request body/payload. 

For these calls, you need to pass an invitation campaign object with all required fields and any fields you want to update or set filled in the body of the payload. We have an example of an invitation campaign object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

POST /invitationCampaign/staff/{staffIdList}

Sends an email invitation to a staff to create an appointment.

Request body/payload: Must pass an invitation campaign object in request body/payload.

For these calls, you need to pass an invitation campaign object with all required fields and any fields you want to update or set filled in the body of the payload. We have an example of an invitation campaign object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

PUT /invitationCampaign

Updates an existing invitation campaign object. Can only be used to update description and expiration date.

Request body/payload: Must pass an invitation campaign object with all fields you want to change filled in.



Invitations API Parameters

Return to Top

Data points passed on in the request URL portion of the API call that are used to filter the data being requested. 

ParameterTypeEndpoints to be used withDescription
pageNumberstringGET /invitationCampaignWorks with the pageSize parameter to determine how invitations get returned following a GET invitationCampaign call. The pageNumber value represents the number of pages on which the invitations that get returned appear.
pageSizeintegerGET /invitationCampaignWorks with the pageNumber parameter to determine how invitations gets returned following a GET invitationCampaign call. The pageSize value represents the number of invitations appearing on each page that gets returned.
professionalIdintegerGET /invitationCampaignShould be set to the professionalId of person who sent the invitationCampaign to be returned. 



Invitations API Request Body/Payloads

Return to Top

The objects below represent the minimum viable objects to pass that are needed to send an invitations object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.

POST /invitationCampaign/client/{clientId} 
{
    "businessId": 43111,
    "description": "Campaign for Sparkles, J, Cat Grooming sent on 05/09/2023 @ 11:45AM",
    "email": {Email object for email of specified invitation campaign - for more info, see Emails API page},
    "emailTemplateId": 217246,
    "eventDefinitionList": [],
    "parameterMap": {
        "clientId": 6444669,
        "coordStaffId": 77961,
        "jobId": 57804,
        "jobRequisitionId": 62883,
        "locationId": 495584,
        "reasonId": 255109,
        "requisitionNumber": "1",
        "staffId": 77961,
    },
    "professionalId": 77961,
	"appointmentIntentId": 1234,
    "status": null
}
PUT /invitationCampaign 
{
    "businessId": 43111,
    "calendarId": null,
    "coordinatorStaffId": null,
    "createdDate": 1684245327502,
    "createdUser": "JoeSchmo",
    "description": "Campaign for Sparkles, J, Cat Grooming sent on 05/16/2023 @ 9:55AM",
    "disclaimerFormUUid": null,
    "email": null,
    "emailTemplateId": 217246,
    "employmentDurationType": null,
    "eventDefinitionList": null,
    "expireDate": "2023-05-31",
    "invitationCampaignId": 673515,
    "jobRequisitionId": null,
    "jobTitle": null,
    "locationId": null,
    "locationName": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "parameterMap": null,
    "parameters": "{\"staffId\":\"77961\",\"coordStaffId\":\"77961\",\"reasonId\":\"255109\",\"locationId\":\"495584\",\"jobId\":\"57804\",\"requisitionNumber\":\"1\",\"jobRequisitionId\":\"62883\"}",
    "professionalId": 77961,
	"appointmentIntentId": 1234,
    "reasonId": null,
    "requisitionNumber": null,
    "staffId": null,
    "status": null,
    "waitListId": null
}



Invitations API Responses

Return to Top

GET /invitation/{invitationId} 
{
    "businessId": 43111,
    "clickDate": 1540317889771,
    "clicked": true,
    "completed": true,
    "completedDate": 1540317921105,
    "createdDate": 1540317840787,
    "createdUser": "JoeSchmo",
    "declineDate": null,
    "declined": false,
    "email": {Email object for email of specified invitation - for more info, see emails API page},
    "invitationCampaignId": 123733,
    "invitationUUId": "ivtce7769a717fa480a907847b99c4574d1",
    "modifiedDate": 1540317921105,
    "modifiedUser": "WebClient",
    "objectId": 5146945,
    "objectType": "CLIENT",
    "openDate": 1540317881254,
    "opened": true,
    "sent": true,
    "status": "COMPLETED",
    "unsubscribed": false
}
GET /invitation/invitationCampaign/{invitationCampaignId} 
[{
    "businessId": 43111,
    "clickDate": 1540390475194,
    "clicked": true,
    "completed": false,
    "completedDate": null,
    "createdDate": 1540390976818,
    "createdUser": "JoeSchmo",
    "declineDate": null,
    "declined": false,
    "email": {Email object for email of specified invitation - for more info, see Emails API page},
    "invitationCampaignId": 124359,
    "invitationUUId": "ivt15dc6e1c815e416f85e9c6cf8bdc2118",
    "modifiedDate": 1540391025551,
    "modifiedUser": "WebClient",
    "objectId": 5146945,
    "objectType": "CLIENT",
    "openDate": null,
    "opened": false,
    "sent": true,
    "status": "CLICKED",
    "unsubscribed": false
}]
GET /invitationCampaign 
[{
    "businessId": 43111,
    "calendarId": null,
    "coordinatorStaffId": null,
    "createdDate": 1539962301620,
    "createdUser": "JoeSchmo",
    "description": "Campaign sent on 10/19/2018 @ 11:18AM",
    "disclaimerFormUUid": null,
    "email": null,
    "emailTemplateId": 70689,
    "employmentDurationType": null,
    "eventDefinitionList": null,
    "expireDate": null,
    "invitationCampaignId": 121587,
    "jobRequisitionId": null,
    "jobTitle": null,
    "locationId": null,
    "locationName": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "parameterMap": null,
    "parameters": "{\"staffId\":\"77961\",\"coordStaffId\":\"298660\",\"reasonId\":\"434637\",\"locationId\":\"81181\",\"jobId\":\"67044\",\"clientId\":\"5360110\",\"requisitionNumber\":\"7\",\"jobRequisitionId\":\"72420\"}",
    "professionalId": 77961,
    "reasonId": null,
    "requisitionNumber": null,
    "staffId": null,
    "status": null,
    "waitlistId": null
}]
GET /invitationCampaign/{invitationCampaignId} 
[{
    "businessId": 43111,
    "coordinatorStaffId": null,
    "createdDate": 1540391632592,
    "createdUser": "JoeSchmo",
    "description": "Campaign sent on 10/19/2018 @ 11:18AM",
    "disclaimerFormUUid": null,
    "email": null,
    "emailTemplateId": 70689,
    "employmentDurationType": null,
    "eventDefinitionList": null,
    "expireDate": 1540944000000,
    "invitationCampaignId": 1243292,
    "jobRequisitionId": null,
    "jobTitle": null,
    "locationId": 81181,
    "locationName": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "parameterMap: null,
    "parameters": "{\"staffId\":\"77961\",\"coordStaffId\":\"298660\",\"reasonId\":\"434637\",\"locationId\":\"81181\",\"jobId\":\"67044\",\"clientId\":\"5360110\",\"requisitionNumber\":\"7\",\"jobRequisitionId\":\"72420\"}",
    "professionalId": 77961,
    "reasonId": null,
    "requisitionNumber": null,
    "staffId": null,
    "status": null,
    "waitlistId": null
}]
POST /invitationCampaign/client/{clientIdList} 
{
    "businessId": 43111,
    "calendarId": null,
    "coordinatorStaffId": 77961,
    "createdDate": 1540306834662,
    "createdUser": "JoeSchmo",
    "description": "Campaign set on 10/23/2018 @ 11:00AM",
    "disclaimerFormUUid": null,
    "email": {Email object connected to specified invitation campaign - for more info, see Emails API page},
    "emailTemplateId": 70689,
    "employmentDurationType": null,
    "eventDefinitionList": [{
        "active": true,
        "businessId": 43111,
        "createdDate": 1540391632663,
        "description": null,
        "eventActions": [{
            "actionType": "SEND_EMAIL",
            "active": true,
            "businessId": 43111,
            "createdDate": 1540391632670,
            "createdUser": "JoeSchmo",
            "emailCategoryId": null,
            "emailTemplateId": 12937,
            "eventActionId": 76757,
            "eventDefnId": 76691,
            "modifiedDate": null,
            "modifiedUser": null
        }],
        "eventDefnId": 76691,
        "eventType": {
            "eventCategory": null,
            "eventType": null,
            "eventTypeId": 9,
            "objectType": null
        },
        "groupIdList": null,
        "locationIdList": null,
        "modifiedDate": null,
        "modifiedUser": null,
        "newStatus": "COMPLETED",
        "objectId": 124392,
        "objectType": "INVITATION_CAMPAIGN",
        "objectUUId": null,
        "oldStatus": "*",
        "professionalIdList": null,
        "reasonIdList": null,
        "triggerHours": null
    }],
    "expireDate": 1540944000000,
    "invitationCampaignId": 124392,
    "jobRequisitionId": null,
    "jobTitle": null,
    "locationId": 81181,
    "locationName": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "parameterMap": {
        "clientId": "6444669",
        "coordStaffId": "77961",
        "jobId": "57804",
        "jobRequisitionId": "62883",
        "locationId": "81181",
        "reasonId": "255109", 
        "requisitionNumber": "1",
        "staffId: "82275"
     },
    "parameters": "{\"staffId\":\"77961\",\"coordStaffId\":\"77961\",\"reasonId\":\"255109\",\"locationId\":\"495584\",\"jobId\":\"57804\",\"clientId\":\"6444669\",\"requisitionNumber\":\"1\",\"jobRequisitionId\":\"62883\"}",
    "professionalId": 77961,
	"appointmentIntentId": 1234,
    "reasonId": 255109,
    "requisitionNumber": null,
    "staffId": 82275,
    "status": null
}
POST /invitationCampaign/staff{staffIdList} 
{
    "businessId": 43111,
    "coordinatorStaffId": 77961,
    "createdDate": 1574350992582,
    "createdUser": "MORGANKEARNEY",
    "description": "Campaign for Beach, Jonny Amante, Guided meditation sent on 11/21/2019 @ 10:40AM",
    "email": {Email object connected to specified invitation campaign - for more info, see emails API page},
    "emailTemplateId": 155556,
    "employmentDurationType": null,
    "eventDefinitionList": [],
    "expireDate": null,
    "invitationCampaignId": 259369,
    "jobRequisitionId": null,
    "jobTitle": null,
    "locationId": 81181,
    "locationName": null,
    "modifiedDate": null,
    "modifiedUser": null,
    "parameterMap": {
        "staffId": "81155", 
        "coordStaffId": "77961", 
        "reasonId": "153346", 
        "locationId": "81181"
        },
    "parameters": "{\"staffId\":\"77961\",\"coordStaffId\":\"77961\",\"reasonId\":\"255109\",\"locationId\":\"495584\",\"jobId\":\"57804\",\"clientId\":\"6444669\",\"requisitionNumber\":\"1\",\"jobRequisitionId\":\"62883\"}",
    "professionalId": 77961,
	"appointmentIntentId": 1234,
    "reasonId": 153346,
    "requisitionNnmber": null,
    "staffId": 81155,
    "status": null
}
PUT /invitationCampaign 
{
    "businessId": 43111,
    "calendarId": null,
    "coordinatorStaffId": null,
    "createdDate": 1539956304696,
    "createdUser": "JoeSchmo",
    "description": "Campaign set on 10/19/2018 @ 9:38AM",
    "disclaimerFormUUid": null,
    "email": null,
    "emailTemplateId": 70689,
    "employmentDurationType": null,
    "eventDefinitionList": null,
    "expireDate": 1540944000000,
    "invitationCampaignId": 121455,
    "jobRequisitionId": null,
    "jobTitle": null,
    "locationId": null,
    "locationName": null,
    "modifiedDate": 1540302776156,
    "modifiedUser": "JoeSchmo",
    "parameterMap": null,
    "parameters": "{\"staffId\":\"77961\",\"coordStaffId\":\"77961\",\"reasonId\":\"255109\",\"locationId\":\"495584\",\"jobId\":\"57804\",\"requisitionNumber\":\"1\",\"jobRequisitionId\":\"62883\"}",
    "professionalId": 77961,
	"appointmentIntentId": 1234,
    "reasonId": null,
    "requisitionNumber": null,
    "staffId": null,
    "status": null,
    "waitlistId": null
}



Invitations Object Values

Return to Top

invitationCampaign

Property NameTypeRequiredDescription
businessIdintegerYesProvides unique numeric ID for the business to which the specified invitation campaign belongs.
calendarIdinteger
Provides unique numeric ID for the calendar to which the specified invitation campaign belongs.
coordinatorStaffIdinteger
Provides unique numeric ID for any coordinator staff connected to the specified invitation campaign.
createdDateinteger
Displays as date the specified invitation campaign was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
createdUserstring
Displays as username of the user who created the specified invitation campaign.
descriptionstring
Displays as description of the specified invitation campaign.
disclaimerFormUUidstring
Provides unique alphanumeric ID for any disclaimer form connected to the specified invitation campaign. 
emailobjectYesDisplays as email object connected to the specified invitation campaign - for more info, see Emails API page.
emailTemplateIdinteger
Provides unique numeric ID of email template used for the specified invitation campaign.
employmentDurationTypestring
Displays as a string that can be merged to the specified invitation with the tag REQ_DURATION_TYPE%.
eventDefinitionListarray
Displays as an array of eventDefinition objects. For more information, see Events API page.
expireDateinteger
Displays as date the specified invitation campaign is set to expire in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
invitationCampaignIdintegerYes, on PUT callsProvides unique numeric ID for the specified invitation campaign.
jobRequisitionIdinteger
Provides unique numeric requisition ID for the specified job.
jobTitlestring
Displays as the job title entered on business' account.
modifiedDateinteger
Displays as date the specified invitation campaign was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. 
modifiedUserstring
Displays as username of the user who last modified the specified invitation campaign.
parameterMapobject
Displays parameters for call being made in object form.
parametersstring
Displays as string representations of parameters for call being made.
professionalIdinteger
Provides unique numeric ID for any staff connected to the specified invitation campaign.
reasonIdinteger
Provides unique numeric ID for any reason connected to the specified invitation campaign.
requisitionNumberinteger
Displays as number stored on the specified job requisition. Requisition numbers are used to connect candidates to appointments booked.
staffIdinteger
Provides unique numeric ID for any staff connected to the specified invitation campaign.
statusstring
Displays as status of the specified invitation campaign.
waitlistIdinteger
Provides unique numeric ID for any waitlist connected to the specified invitation campaign.
appointmentIntentIdinteger
Provides unique numeric ID for any appointment intents connected to the specified invitation campaign.

invitation

Property NameTypeDescription
businessIdintegerProvides unique numeric ID for the business to which the specified invitation belongs.
clickDateintegerDisplays as date the specified invitation was clicked in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
clickedbooleanIndicates whether or not the specified invitation should show as clicked.
completedbooleanIndicates whether or not the specified invitation should show as completed.
completedDateintegerDisplays as date the specified invitation was completed in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createdDateintegerDisplays as date the specified invitation was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
createdUserstringDisplays as username of user who created the specified invitation.
declineDateintegerDisplays as date the specified invitation was declined in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
declinedbooleanIndicates whether or not the specified invitation should show as declined.
emailobjectDisplays as email object connected to the specified invitation.
invitationCampaignIdintegerProvides unique numeric ID for invitation campaign connected to the specified invitation.
invitationUUIdstringProvides unique alphanumeric ID for the specified invitation.
modifiedDateintegerDisplays as date the specified invitation was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
modifiedUserstringDisplays as user who last modified the specified invitation.
objectIdintegerProvides unique numeric ID for object connected to the specified invitation.
objectTypestringDisplays as the objectType of the specified invitation. Has available options "CLIENT'", "STAFF", and "APPOINTMENT".
openDateintegerDisplays as date the specified invitation was opened in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.
openedbooleanIndicates whether or not the specified invitation has been opened by recipient.
sentbooleanIndicates whether or not the specified invitation has successfully sent.
statusstringDisplays as status of the specified invitation. Has available options "PENDING", "SENT", "OPENED", "CLICKED", "COMPLETED", "DECLINED"
unsubscribedbooleanIndicates whether or not the specified invitation should show as unsubscribed.