Get Leads List

  • API: getLeads

  • Purpose & Use Cases: You can use this API endpoint to retrieve the list of leads.

  • Request:

Attribute Name Data Type Required Details
propertyId ID No Unique identifier for the property
propertyExternalId ID No Unique external identifier for the property
roomId ID No Unique identifier for the room
studentId ID No Unique identifier for the student
pageNumber Int No The number of the page
pageSize Int No The size of the page
sortBy LeadSortBy No The field for lead sorting; Possible values: UPDATED_AT CREATED_AT
sortDirection SortDirection No The leadSortDirection; Possible values: ASCENDING DESCENDING
createdFrom Date No The created date from in format ISO 8601 (YYYY-MM-DD)
createdTo Date No The created date to in format ISO 8601 (YYYY-MM-DD)
stage LeadStage No The stage of the lead; Possible values: WAITING_FOR_CONFIRMATION WAITING_FOR_PAYMENT WAITING_FOR_CHECK_IN AFTER_SALES_INTERVENTION REFUNDING FILLING_PERSONAL_INFO SIGNING_AGREEMENT MAKING_PAYMENT BOOKING_CONFIRMED SELECTING_PAYMENT_PLAN IN_PROGRESS LOST CANCELLED CHECKED_IN COMPLETED
bookingJourney LeadBookingJourney No The bookingJourney of the lead; Possible values: BOOK CONNECT_STUDENT_SUITE CONNECT LIST 
  QUERY
query GetLeads(
    $pageNumber: Int,
    $pageSize: Int,
    $sortBy: PropertySortBy,
    $sortDirection: SortDirection,
    $createdFrom: Date,
    $createdTo: Date,
    $propertyId: ID,
    $propertyExternalId: NonEmptyString,
    $roomId: ID,
    $bookingJourney: LeadBookingJourney,
    $stage: LeadStage,
    $studentId: ID
    ) {
  getLeads(
    pageNumber: $pageNumber,
    pageSize: $pageSize,
    sortBy: $sortBy,
    sortDirection: $sortDirection,
    createdFrom: $createdFrom,
    createdTo: $createdTo,
    propertyId: $propertyId,
    propertyExternalId: $propertyExternalId,
    roomId: $roomId,
    bookingJourney: $bookingJourney,
    stage: $stage,
    studentId: $studentId
    ) {
    pageInfo {
      total
      totalPages
      currentPage
      pageSize
    }
    leads {
      moveInDate
      moveOutDate
      id
      hash
      currency
      billingCycle
      createdAt
      bookingJourney
      propertyId
      propertyName
      rateAvailabilityId
      referenceId
      roomId
      roomName
      stage
      studentId
      room {
        externalId
      }
      property {
        externalId
      }
    }
  }
}

GRAPHQL VARIABLES
{
  "pageNumber": 1,
  "pageSize": 2,
  "sortBy": "UPDATED_AT",
  "sortDirection": "DESCENDING",
  "createdFrom": null,
  "createdTo": null,
  "propertyId": null,
  "propertyExternalId": null,
  "roomId": null,
  "bookingJourney": null,
  "stage": null,
  "studentId": null
}
  • Response:
  {
    "data": {
        "getLeads": {
            "pageInfo": {
                "total": 149,
                "totalPages": 75,
                "currentPage": 1,
                "pageSize": 2
            },
            "leads": [
                {
                    "moveInDate": "2024-07-31",
                    "moveOutDate": "2024-08-31",
                    "id": "eyJ0eXBlIjoiT3JkZXIiLCJpZCI6MTAxNX0=",
                    "hash": "v018d335068eb8cdef76acdf2105509486d",
                    "currency": "GBP",
                    "billingCycle": "WEEKLY",
                    "createdAt": "2024-07-31T02:57:28+00:00",
                    "bookingJourney": "MESSAGE_PROPERTY",
                    "propertyId": "eyJ0eXBlIjoiUHJvcGVydHkiLCJpZCI6MTA0NDc3NH0=",
                    "propertyName": "test tranfer property 02",
                    "rateAvailabilityId": "eyJ0eXBlIjoiUmF0ZUF2YWlsYWJpbGl0eSIsImlkIjoxMDAwMzA1MjEzfQ==",
                    "referenceId": "HB956382086",
                    "roomId": "eyJ0eXBlIjoiUm9vbSIsImlkIjoxMDA3NTEyOX0=",
                    "roomName": "Untitled Room 1",
                    "stage": "WAITING_FOR_CONFIRMATION",
                    "studentId": "69487",
                    "room": {
                        "externalId": "update externalId01"
                    },
                    "property": {
                        "externalId": null
                    }
                },
                {
                    "moveInDate": "2024-07-31",
                    "moveOutDate": "2024-08-31",
                    "id": "eyJ0eXBlIjoiT3JkZXIiLCJpZCI6MTAxNn0=",
                    "hash": "v018d335068eb8cdef76acdf21055094862",
                    "currency": "GBP",
                    "billingCycle": "WEEKLY",
                    "createdAt": "2024-07-31T03:19:37+00:00",
                    "bookingJourney": "RESERVE_ROOM",
                    "propertyId": "eyJ0eXBlIjoiUHJvcGVydHkiLCJpZCI6MTA0NDc3M30=",
                    "propertyName": "test transfer property 01",
                    "rateAvailabilityId": "eyJ0eXBlIjoiUmF0ZUF2YWlsYWJpbGl0eSIsImlkIjoxMDAwMzA1MjA0fQ==",
                    "referenceId": "IB624736261",
                    "roomId": "eyJ0eXBlIjoiUm9vbSIsImlkIjoxMDA3NTEyMX0=",
                    "roomName": "Untitled Room1",
                    "stage": "LOST",
                    "studentId": "69487",
                    "totalPrice": "491.58",
                    "room": {
                        "externalId": null
                    },
                    "property": {
                        "externalId": null
                    }
                }
            ]
        }
    }
}
  • Error Message:
Error Message Description
Property not found Unable to find a property by args.propertyExternalId

Get Lead Detail

  • API: getLead

  • Purpose & Use Cases: You can use this API endpoint to retrieve lead details.

  • Request:

Attribute Name Data Type Required Details
referenceId String Yes Unique identifier for the lead
hash String Yes Hash for the lead 
  QUERY
query GetLead($referenceId: String!, $hash: String!) {
  getLead(
    referenceId: $referenceId
    hash: $hash) {
    lead {
      id
      hash
      referenceId
      stage
      currency
      moveInDate
      moveOutDate
      propertyId
      propertyName
      roomId
      roomName
      roomCategory
      rateAvailabilityId
      studentData
      createdAt
      updatedAt
      rejectedBy
      rejectedReason
      cancelledBy
      cancelledAt
      cancelledReason
      cancellationNote
      paidAt
      lostAt
      completedAt
      confirmedAt
      totalPrice
      totalDeposit
      totalFee
      totalRental
      property {
        externalId
        addressCity
      }
      room {
        externalId
      }
      rateAvailability {
        externalId
      }
    }
  }
}


GRAPHQL VARIABLES
{
  "referenceId": "HB584621423",
  "hash": "v01552e312769826aec50d936f998b0c5d5"
}
  • Response:
  {
    "data": {
        "getLead": {
            "lead": {
                "id": "eyJ0eXBlIjoiT3JkZXIiLCJpZCI6NDY1fQ==",
                "hash": "v018d335068eb8cdef76acdf2105509486d",
                "referenceId": "HB119759510",
                "stage": "LOST",
                "currency": "USD",
                "moveInDate": "2021-03-29",
                "moveOutDate": "2021-04-26",
                "propertyId": "eyJ0eXBlIjoiUHJvcGVydHkiLCJpZCI6MTAzMjgzOH0=",
                "propertyName": "test hercules456",
                "roomId": "eyJ0eXBlIjoiUm9vbSIsImlkIjoxMDA1OTc3M30=",
                "roomName": "Untitled Room1",
                "roomCategory": "SHARED_ROOM",
                "rateAvailabilityId": "eyJ0eXBlIjoiUmF0ZUF2YWlsYWJpbGl0eSIsImlkIjoxMDAwMTg3MjMxfQ==",
                "studentData": {
                    "id": 67271,
                    "city": "lon",
                    "state": "w",
                    "gender": "male",
                    "country": "CHN",
                    "nationality": "AFG",
                    "postalCode": "12",
                    "addressLines": "dsddd",
                    "dateOfBirth": "1995-03-01",
                    "documentType": "passport",
                    "emailAddress": "tyra.huang+20210329@student.com",
                    "documentNumber": "",
                    "passportLastName": "q",
                    "passportFirstName": "d",
                    "destinationUniversity": "university-of-missouri",
                    "studyMajor": "IT",
                    "otherPreferences": "Nothing else",
                },
                "createdAt": "2021-03-29T03:26:33+00:00",
                "updatedAt": "2024-11-26T09:16:25+00:00",
                "rejectedBy": null,
                "rejectedReason": null,
                "cancelledBy": "aa92fd71-f517-4276-88ef-ba42691fe1af",
                "cancelledAt": "2021-03-29T03:27:05+00:00",
                "cancelledReason": "No longer looking for accommodation",
                "cancellationNote": null,
                "paidAt": null,
                "lostAt": "2021-03-29T03:27:05+00:00",
                "completedAt": null,
                "confirmedAt": null,
                "totalPrice": "236.07",
                "totalDeposit": "220.00",
                "totalFee": "3.00",
                "totalRental": "13.07",
                "property": {
                    "externalId": "property_test_external_id",
                    "addressCity": "Beverly Hills",
                },
                "room": {
                    "externalId": "room_test_external_id",
                },
                "rateAvailability": "rateAvailability": {
                    "externalId": "rateAvailability_test_external_id",
                },
            }
        }
    }
}
  • Error Message:
Error Message Description
ReferenceId not found Unable to find an order by the provided
You are not allowed to access this order You do not have permission to access this lead, please check your x-api-token

Download lead’s document

  • API: /api/v1/download/lead/document

  • Purpose & Use Cases: You can use this API endpoint to download lead’s document.

  • Request:

Attribute Name Data Type Required Details
documentId String Yes The documentId of the lead
referenceId String Yes The referenceId of the lead 
  Query Params
documentId eyJ0eXBlIjoiVXBsb2FkRmlsZSIsImlkIjo1NjAzfQ
referenceId HB723157607

URL
https://public-gateway.student.com/api/v1/download/lead/document?documentId=eyJ0eXBlIjoiVXBsb2FkRmlsZSIsImlkIjo1NjAzfQ&referenceId=HB723157607