Pexip Engage API documentation

Create an appointment

POST /appointments

OAuth2

Create an appointment

Headers

Authorization string

Bearer token used for authorization

Minimum length is 1.
X-Correlation-Id string

Unique identifier to allow referencing a particular transaction or event chain

Minimum length is 1.
Accept-Language string

Returns the requested resources translated according to the passed languages (see translatable resources)

Minimum length is 1.

application/json

Body Required

start string(date-time) Required

Minimum length is 1.
end string(date-time) Required

Minimum length is 1.
subjectId string Required

Minimum length is 1.
officeId string Required

Minimum length is 1.
appointmentParticipants array[object] Required

At least 2 elements.
Hide appointmentParticipants attributes Show appointmentParticipants attributes object
- role string Required
  
  Values are PRIMARY or SECONDARY.
- participantId string Required
  
  Minimum length is 1.
- type string Required
  
  Values are CUSTOMER or EMPLOYEE.
- Additional properties are NOT allowed
answers array[object] | null
Hide answers attributes Show answers attributes object
- value string | null
  
  Minimum length is 1.
- selectedAnswerOptions array[object] | null
  Hide selectedAnswerOptions attributes Show selectedAnswerOptions attributes object
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
- questionId string Required
  
  Minimum length is 1.
- Additional properties are NOT allowed
callbackRequestId string | null

Minimum length is 1.
location object | null
Hide location attributes Show location attributes
- postalCode string | null
  
  Minimum length is 1.
- countryCode string Required
  
  Minimum length is 2, maximum length is 2.
- geolocation object | null
  Hide geolocation attributes Show geolocation attributes
  
  latitude number Required
  
  Minimum value is -90, maximum value is 90.
  
  longitude number Required
  
  Minimum value is -180, maximum value is 180.
  
  Additional properties are NOT allowed
- translations object Required
  Hide translations attributes Show translations attributes
  
  city array[object] Required
  
  At least 1 element.
  
  Hide city attributes Show city attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  state array[object]
  
  At least 0 elements.
  
  Hide state attributes Show state attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  street1 array[object] Required
  
  At least 1 element.
  
  Hide street1 attributes Show street1 attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  street2 array[object]
  
  At least 0 elements.
  
  Hide street2 attributes Show street2 attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  Additional properties are NOT allowed
- Additional properties are NOT allowed
listingId string | null

Minimum length is 1.
leadSegmentId string | null

Minimum length is 1.
meetingType string Required

Values are OFFICE, ON_LOCATION, PHONE, or VIDEO.
externalId string | null

Minimum length is 1, maximum length is 255.
hybrid boolean | null
trailingBufferTime integer | null

Minimum value is 0. Default value is 0.
internalNotes string | null

Minimum length is 1.
metadata
Additional properties are NOT allowed

Responses

• 201 application/json

Successful operation
Hide response attributes Show response attributes object
- data object Required
  
  Hide data attributes Show data attributes
  
  id string Required
  
  Minimum length is 1.
  
  externalId string | null
  
  Minimum length is 1, maximum length is 255.
  
  start string(date-time) | null
  
  Minimum length is 1.
  
  end string(date-time) | null
  
  Minimum length is 1.
  
  subject object Required
  
  Hide subject attributes Show subject attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  office object Required
  
  Hide office attributes Show office attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  appointmentParticipants array[object] Required
  
  At least 2 elements.
  
  Hide appointmentParticipants attributes Show appointmentParticipants attributes object
  
  role string Required
  
  Values are PRIMARY or SECONDARY.
  
  participant object Required
  
  Hide participant attribute Show participant attribute
  
  id string Required
  
  Minimum length is 1.
  
  type string Required
  
  Values are CUSTOMER or EMPLOYEE.
  
  videoUrl string(uri) | null
  
  Minimum length is 1.
  
  videoTestUrl string(uri) | null
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  answers array[object] Required
  
  Hide answers attributes Show answers attributes object
  
  value string | null
  
  Minimum length is 1.
  
  selectedAnswerOptions array[object] | null
  
  Hide selectedAnswerOptions attributes Show selectedAnswerOptions attributes object
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  id string Required
  
  Minimum length is 1.
  
  form object Required
  
  Hide form attributes Show form attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  question object Required
  
  Hide question attributes Show question attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  answerType string Required
  
  Values are APPOINTMENT_CANCELLATION, APPOINTMENT_COMPLETION, CALLBACK_REQUEST, QUALIFICATION, or SUBJECT_QUESTIONNAIRE.
  
  createdAt string(date-time) Required
  
  Minimum length is 1.
  
  updatedAt string(date-time) Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  callbackRequest object | null
  
  Hide callbackRequest attributes Show callbackRequest attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  listing object | null
  
  Hide listing attributes Show listing attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  leadSegment object | null
  
  Hide leadSegment attributes Show leadSegment attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  meetingType string Required
  
  Values are OFFICE, ON_LOCATION, PHONE, or VIDEO.
  
  status string Required
  
  Values are ACCEPTED, ALTERNATIVE_DATE_REQUESTED, CANCELLED, COMPLETED, INCOMING_REQUEST, NO_SHOW, or OUTGOING_INVITE.
  
  hybrid boolean Required
  
  trailingBufferTime integer Required
  
  Minimum value is 0.
  
  internalNotes string | null
  
  Minimum length is 1.
  
  metadata
  
  createdAt string(date-time) Required
  
  Minimum length is 1.
  
  createdBy object | null
  
  Hide createdBy attributes Show createdBy attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  createdByType string Required
  
  Values are CUSTOMER, EMPLOYEE, or OTHER.
  
  createdFrom string Required
  
  Values are BACKOFFICE_APP, OTHER, PARTNER_BOOKING_APP, or PLUGIN.
  
  updatedAt string(date-time) Required
  
  Minimum length is 1.
  
  updatedBy object | null
  
  Hide updatedBy attributes Show updatedBy attributes
  
  id string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  updatedByType string Required
  
  Values are CUSTOMER, EMPLOYEE, or OTHER.
  
  updatedFrom string Required
  
  Values are BACKOFFICE_APP, OTHER, PARTNER_BOOKING_APP, or PLUGIN.
  
  location object | null
  
  Hide location attributes Show location attributes
  
  city object | null Required
  
  Hide city attributes Show city attributes
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Additional properties are NOT allowed
  
  state object | null Required
  
  Hide state attributes Show state attributes
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Additional properties are NOT allowed
  
  street1 object | null Required
  
  Hide street1 attributes Show street1 attributes
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Additional properties are NOT allowed
  
  street2 object | null Required
  
  Hide street2 attributes Show street2 attributes
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Additional properties are NOT allowed
  
  postalCode string | null
  
  Minimum length is 1.
  
  countryCode string Required
  
  Minimum length is 2, maximum length is 2.
  
  formattedAddress string Required
  
  Minimum length is 1.
  
  geolocation object Required
  
  Hide geolocation attributes Show geolocation attributes
  
  latitude number Required
  
  Minimum value is -90, maximum value is 90.
  
  longitude number Required
  
  Minimum value is -180, maximum value is 180.
  
  Additional properties are NOT allowed
  
  translations object Required
  
  Hide translations attributes Show translations attributes
  
  city array[object] Required
  
  At least 1 element.
  
  Hide city attributes Show city attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  state array[object]
  
  At least 0 elements.
  
  Hide state attributes Show state attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  street1 array[object] Required
  
  At least 1 element.
  
  Hide street1 attributes Show street1 attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  street2 array[object]
  
  At least 0 elements.
  
  Hide street2 attributes Show street2 attributes object
  
  language string Required
  
  Values are da, de, el, en, es, fr, ja, nl, no, or pl.
  
  value string Required
  
  Minimum length is 1.
  
  Additional properties are NOT allowed
  
  Additional properties are NOT allowed
  
  Additional properties are NOT allowed
- Additional properties are NOT allowed
• 422 application/json
Business validation failed
- ANSWER_SELECTED_OPTIONS_FOR_NON_SELECTION_TYPE
- ANSWER_VALUE_FOR_SELECTION_TYPE
- APPOINTMENT_LOCATION_REQUIRED
- APPOINTMENT_NO_AVAILABILITY
- APPOINTMENT_PARTICIPANTS_NOT_UNIQUE
- APPOINTMENT_PRIMARY_CUSTOMER_MISSING
- APPOINTMENT_PRIMARY_EMPLOYEE_MISSING
- APPOINTMENT_START_AFTER_END
- LOCATION_GEOCODING_FAILED
- LOCATION_TIME_ZONE_RESOLUTION_FAILED
See Error codes
Hide response attribute Show response attribute object
- errors array[object] Required
  
  At least 1 element.
  
  Hide errors attributes Show errors attributes object
  
  message string Required
  
  Minimum length is 1.
  
  code string Required
  
  Minimum length is 1.
  
  type string Required
  
  Minimum length is 1.
  
  statusCode string Required
  
  Minimum length is 1.
  
  arguments object | null

POST /appointments

curl \
 -X POST https://api.pexipengage.com/enterprises/acme/appointments \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
 -H "X-Correlation-Id: a4f0048e-c983-11ed-afa1-0242ac120002" \
 -H "Accept-Language: en *" \
 -d '{"start":"2022-08-17T09:00:00.000Z","end":"2022-08-17T10:00:00.000Z","subjectId":"123","officeId":"123","appointmentParticipants":[{"role":"PRIMARY","participantId":"123","type":"EMPLOYEE"}],"answers":[{"value":"A colleague","selectedAnswerOptions":[{"id":"123"}],"questionId":"123"}],"callbackRequestId":"123","location":{"postalCode":"9000","countryCode":"BE","geolocation":{"latitude":51.0479466,"longitude":3.6912248},"translations":{"city":[{"language":"en","value":"Lorem ipsum"}],"state":[{"language":"en","value":"Lorem ipsum"}],"street1":[{"language":"en","value":"Lorem ipsum"}],"street2":[{"language":"en","value":"Lorem ipsum"}]}},"listingId":"123","leadSegmentId":"123","meetingType":"OFFICE","externalId":"ABCD1234","hybrid":true,"trailingBufferTime":5,"internalNotes":"Lorem ipsum"}'

Request example

# Headers
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
X-Correlation-Id: a4f0048e-c983-11ed-afa1-0242ac120002
Accept-Language: en *

# Payload
{
  "start": "2022-08-17T09:00:00.000Z",
  "end": "2022-08-17T10:00:00.000Z",
  "subjectId": "123",
  "officeId": "123",
  "appointmentParticipants": [
    {
      "role": "PRIMARY",
      "participantId": "123",
      "type": "EMPLOYEE"
    }
  ],
  "answers": [
    {
      "value": "A colleague",
      "selectedAnswerOptions": [
        {
          "id": "123"
        }
      ],
      "questionId": "123"
    }
  ],
  "callbackRequestId": "123",
  "location": {
    "postalCode": "9000",
    "countryCode": "BE",
    "geolocation": {
      "latitude": 51.0479466,
      "longitude": 3.6912248
    },
    "translations": {
      "city": [
        {
          "language": "en",
          "value": "Lorem ipsum"
        }
      ],
      "state": [
        {
          "language": "en",
          "value": "Lorem ipsum"
        }
      ],
      "street1": [
        {
          "language": "en",
          "value": "Lorem ipsum"
        }
      ],
      "street2": [
        {
          "language": "en",
          "value": "Lorem ipsum"
        }
      ]
    }
  },
  "listingId": "123",
  "leadSegmentId": "123",
  "meetingType": "OFFICE",
  "externalId": "ABCD1234",
  "hybrid": true,
  "trailingBufferTime": 5,
  "internalNotes": "Lorem ipsum"
}

Response examples (201)

{
  "data": {
    "id": "123",
    "externalId": "ABCD1234",
    "start": "2022-08-17T09:00:00.000Z",
    "end": "2022-08-17T10:00:00.000Z",
    "subject": {
      "id": "123"
    },
    "office": {
      "id": "123"
    },
    "appointmentParticipants": [
      {
        "role": "PRIMARY",
        "participant": {
          "id": "string"
        },
        "type": "EMPLOYEE",
        "videoUrl": "https://wwww.example.net/abc123",
        "videoTestUrl": "https://wwww.example.net/abc123"
      }
    ],
    "answers": [
      {
        "value": "A colleague",
        "selectedAnswerOptions": [
          {
            "id": "123"
          }
        ],
        "id": "123",
        "form": {
          "id": "123"
        },
        "question": {
          "id": "123"
        },
        "answerType": "SUBJECT_QUESTIONNAIRE",
        "createdAt": "2022-08-17T19:05:21.362Z",
        "updatedAt": "2022-08-17T19:05:21.362Z"
      }
    ],
    "callbackRequest": {
      "id": "123"
    },
    "listing": {
      "id": "123"
    },
    "leadSegment": {
      "id": "123"
    },
    "meetingType": "OFFICE",
    "status": "ACCEPTED",
    "hybrid": true,
    "trailingBufferTime": 5,
    "internalNotes": "Lorem ipsum",
    "createdAt": "2022-08-17T19:05:21.362Z",
    "createdBy": {
      "id": "123"
    },
    "createdByType": "EMPLOYEE",
    "createdFrom": "BACKOFFICE_APP",
    "updatedAt": "2022-08-17T19:05:21.362Z",
    "updatedBy": {
      "id": "123"
    },
    "updatedByType": "EMPLOYEE",
    "updatedFrom": "BACKOFFICE_APP",
    "location": {
      "city": {
        "language": "en",
        "value": "Lorem ipsum"
      },
      "state": {
        "language": "en",
        "value": "Lorem ipsum"
      },
      "street1": {
        "language": "en",
        "value": "Lorem ipsum"
      },
      "street2": {
        "language": "en",
        "value": "Lorem ipsum"
      },
      "postalCode": "9000",
      "countryCode": "BE",
      "formattedAddress": "string",
      "geolocation": {
        "latitude": 51.0479466,
        "longitude": 3.6912248
      },
      "translations": {
        "city": [
          {
            "language": "en",
            "value": "Lorem ipsum"
          }
        ],
        "state": [
          {
            "language": "en",
            "value": "Lorem ipsum"
          }
        ],
        "street1": [
          {
            "language": "en",
            "value": "Lorem ipsum"
          }
        ],
        "street2": [
          {
            "language": "en",
            "value": "Lorem ipsum"
          }
        ]
      }
    }
  }
}

Response examples (422)

{
  "errors": [
    {
      "message": "string",
      "code": "string",
      "type": "string",
      "statusCode": "string",
      "arguments": {}
    }
  ]
}