This is a library of ready-to-use sample GraphQL queries and mutations for Matterport’s Capture Services API.

Each query and mutation contains a link to try the query in our interactive console. If you are logged into your account at my.matterport.com, you will be able to use the interactive console. If you have a Developer Tools license, the Interactive Console will be able to query all models in your account. If you are in Sandbox mode, it will only be able to query the demo model in your account.

Concepts

A new order begins as a pre-order. When submitting a pre-order, you will receive an id and available dates and times based on the preferences sent. Patching a pre-order with a valid preferred start time will allow you to then submit the pre-order.

An order will contain pricing. If you agree to the provided price, you will be able to submit the order.

When an order has been accepted, it will become a job. Jobs can be modified with a limited scope of fields related to the point of contact, special requests and the scheduled start time. Jobs can also be canceled prior to the accepted date and time.

Sample Queries & Mutations

Create a Pre-Order

Pre-Orders are jobs that have not been submitted. These pending orders can be previewed and modified before submitting.

When creating a pre-order, a list of available times will be returned along with the id for the new pre-order that you will need to use for subsequent mutations to edit the order, submit it and setup a subscription to monitor the progress on the order.

mutation createPreOrder($input: CaptureSvcsPreOrderInput) {
  newPreOrder(input: $input) {
    id
    preOrderStatus
    availability {
      date
      availableSlots {
        startTime
        endTime
      }
    }
  }
}

Variables:

{
  "input": {
    "address": {
      "streetAddressLines": ["801 E William Cannon Dr Suite 401"],
      "administrativeArea": "TX",
      "locality": "Austin",
      "postalCode": "78745",
      "country": "US"
    },
    "specialRequests": "check in at the front desk",
    "totalPropertySize": 3500,
    "propertySizeUnit": "SQUARE_FT",
    "estimateCurrency": "USD",
    "contactName": "Test  User",
    "contactEmail": "youremail@youreemail.com",
    "contactPhone": "555-0000",
    "contactWillBeOnsite": true
  }
}

Sample Response:

{
  "data": {
    "newPreOrder": {
      "id": "agr36qzk217huz5qdqkd076ib",
      "preOrderStatus": "IN_PROGRESS",
      "availability": [
        {
          "date": "2024-12-01T06:00:00Z",
          "availableSlots": [
            {
              "startTime": "2024-12-01T17:00:00Z",
              "endTime": "2024-12-01T17:30:00Z"
            },
            {
              "startTime": "2024-12-01T17:30:00Z",
              "endTime": "2024-12-01T18:00:00Z"
            },
            ...
          ]
        },
        {
          "date": "2024-12-02T06:00:00Z",
          "availableSlots": [
            {
              "startTime": "2024-12-02T13:00:00Z",
              "endTime": "2024-12-02T13:30:00Z"
            },
            {
              "startTime": "2024-12-02T13:30:00Z",
              "endTime": "2024-12-02T14:00:00Z"
            },
            ...
          ]
        }
      ]
    }
  }
}

Try this query in our interactive console

Update a Pre-Order

A pre-order can be updated to change any important information as well as to include the preferredStartTime based on the values returned when the pre-order was created.

mutation editPreOrder($id: ID!, $input: CaptureSvcsPreOrderInput!) {
  patchPreOrder(id: $id, input: $input) {
    id
    preOrderStatus
  }
}

Variables:

{
  "id": "yk2ht2ksp5ech7dcm5tetgigd",
  "input": {
    "propertyType": "RESIDENTIAL",
    "specialRequests": "check in at the front desk.  more data",
    "totalPropertySize": 3500,
    "propertySizeUnit": "SQUARE_FT",
    "preferredStartTime": "2022-04-16T14:00:00Z",
    "contactName": "Test User",
    "contactEmail": "youremail@youremail.com",
    "contactPhone": "555-0000",
    "contactWillBeOnsite": true
  }
}

Sample response:

{
  "data": {
    "patchPreOrder": {
      "id": "agr36qzk217huz5qdqkd076ib",
      "preOrderStatus": "READY_TO_SUBMIT"
    }
  }
}

Try this query in our interactive console

Submit a Pre-Order

Submitting a pre-order with a valid appointment time will create an order.

mutation submitPreOrder($preOrderId: ID!) {
  submitPreOrder(id: $preOrderId) {
    ...OrderFields
  }
}

fragment OrderFields on CaptureSvcsOrder {
  id
  address
  propertyType
  propertyTimeZone
  preferredStartTime
  specialRequests
  addressLatitude
  addressLongitude
  regionId
  jobDuration
  sizeTierPricing
  sizeTier
  price
  customerCurrency
  totalPropertySize
  propertySizeUnit
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
}

Variables:

{
  "preOrderId": "yk2ht2ksp5ech7dcm5tetgigd"
}

Sample response:

{
  "data": {
    "submitPreOrder": {
      "id": "agr36qzk217huz5qdqkd076ib",
      "address": "801 E William Cannon Dr, Austin, Travis County, TX, 78745, US",
      "propertyType": "RESIDENTIAL",
      "propertyTimeZone": "US/Central",
      "preferredStartTime": "2024-12-01T17:00Z[UTC]",
      "specialRequests": "check in at the front desk.  more data",
      "addressLatitude": 30.190227508544922,
      "addressLongitude": -97.77227783203125,
      "regionId": "hgi0sbrcpcffhgt1xcqgtu7bd",
      "jobDuration": 120,
      "sizeTierPricing": "{\"name\":\"tier3\",\"band\":3,\"minsqft\":3001,\"maxsqft\":4000,\"minsqm\":280,\"maxsqm\":372,\"jobhrs\":2.0,\"tierPrice\":{\"usd\":{\"payIn\":428.04},\"gbp\":{\"payIn\":283.2},\"eur\":{\"payIn\":278.4},\"jpy\":{\"payIn\":190558.0}}}",
      "sizeTier": "tier3",
      "price": "428.04",
      "customerCurrency": "USD",
      "totalPropertySize": 3500,
      "propertySizeUnit": "SQUARE_FT",
      "contactName": "Test User",
      "contactEmail": "youremail@youremail.com",
      "contactPhone": "555-0000",
      "contactWillBeOnsite": true
    }
  }
}

Try this query in our interactive console

Preview Order 
mutation previewOrder($orderId: ID!) {
  previewOrder(id: $orderId) {
    ...OrderFields
  }
}

fragment OrderFields on CaptureSvcsOrder {
  id
  address
  propertyType
  propertyTimeZone
  preferredStartTime
  specialRequests
  addressLatitude
  addressLongitude
  regionId
  jobDuration
  sizeTierPricing
  sizeTier
  price
  customerCurrency
  totalPropertySize
  propertySizeUnit
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
}

Variables:

{
  "orderId": "upgawir53nn26furm19nqtwyc"
}

Sample response:

{
  "data": {
    "previewOrder": {
      "id": "agr36qzk217huz5qdqkd076ib",
      "address": "801 E William Cannon Dr, Austin, Travis County, TX, 78745, US",
      "propertyType": "RESIDENTIAL",
      "propertyTimeZone": "US/Central",
      "preferredStartTime": "2024-12-01T17:00Z[UTC]",
      "specialRequests": "check in at the front desk.  more data",
      "addressLatitude": 30.190227508544922,
      "addressLongitude": -97.77227783203125,
      "regionId": "hgi0sbrcpcffhgt1xcqgtu7bd",
      "jobDuration": 120,
      "sizeTierPricing": "{\"name\":\"tier3\",\"band\":3,\"minsqft\":3001,\"maxsqft\":4000,\"minsqm\":280,\"maxsqm\":372,\"jobhrs\":2.0,\"tierPrice\":{\"usd\":{\"payIn\":428.04},\"gbp\":{\"payIn\":283.2},\"eur\":{\"payIn\":278.4},\"jpy\":{\"payIn\":190558.0,}}}",
      "sizeTier": "tier3",
      "price": "428.04",
      "customerCurrency": "USD",
      "totalPropertySize": 3500,
      "propertySizeUnit": "SQUARE_FT",
      "contactName": "Test User",
      "contactEmail": "youremail@youremail.com",
      "contactPhone": "555-0000",
      "contactWillBeOnsite": true
    }
  }
}

Try this query in our interactive console

Update an Order 
mutation patchJob($id: ID!, $input: CaptureSvcsJobInput!) {
  patchJob(id: $id, input: $input) {
    ...JobFields
  }
}

fragment JobFields on CaptureSvcsJob {
  id
  orderId
  address
  propertySize
  propertySizeUnit
  propertyType
  propertyTimeZone
  regionId
  duration
  status
  scheduledStartTime
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
  specialRequests
  techUserId
  techAccountId
  techNotesComments
  custUserId
  custAccountId
  modelIds
  created
  modified
}

Variables:

{
  "id": "agr36qzk217huz5qdqkd076ib",
  "input": {
    "specialRequests": "Hello Testing"
  }
}

Sample response:

{
  "data": {
    "patchJob": {
      "id": "agr36qzk217huz5qdqkd076ib",
      "orderId": "agr36qzk217huz5qdqkd076ib",
      "address": "801 E William Cannon Dr, Austin, Travis County, TX, 78745, US",
      "propertySize": 3500,
      "propertySizeUnit": "SQUARE_FT",
      "propertyType": "RESIDENTIAL",
      "propertyTimeZone": "US/Central",
      "regionId": "hgi0sbrcpcffhgt1xcqgtu7bd",
      "duration": 120,
      "status": "BOOKED",
      "scheduledStartTime": "2024-12-01T17:00:00Z",
      "contactName": "Test User",
      "contactEmail": "youremail@youremail.com",
      "contactPhone": "555-0000",
      "contactWillBeOnsite": true,
      "specialRequests": "Hello Testing",
      "techUserId": "doWxoShciw9",
      "techAccountId": "UFDpezfAVoU",
      "techNotesComments": null,
      "custUserId": "zojRpo1rhox",
      "custAccountId": "1PhHdqxAn9V",
      "modelIds": null,
      "created": "2024-11-28T05:59:11Z",
      "modified": "2024-11-28T06:02:03Z"
    }
  }
}

Try this query in our interactive console

Submit Order 
mutation submitOrder($orderId: ID!) {
  submitOrder(id: $orderId) {
    ...OrderFields
  }
}

fragment OrderFields on CaptureSvcsOrder {
  id
  address
  propertyType
  propertyTimeZone
  preferredStartTime
  specialRequests
  addressLatitude
  addressLongitude
  regionId
  jobDuration
  sizeTierPricing
  sizeTier
  price
  customerCurrency
  totalPropertySize
  propertySizeUnit
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
}

Variables:

{
  "orderId": "agr36qzk217huz5qdqkd076ib"
}

Sample response:

{
  "data": {
    "submitOrder": {
      "id": "agr36qzk217huz5qdqkd076ib",
      "address": "801 E William Cannon Dr, Austin, Travis County, TX, 78745, US",
      "propertyType": "RESIDENTIAL",
      "propertyTimeZone": "US/Central",
      "preferredStartTime": "2024-12-01T17:00Z[UTC]",
      "specialRequests": "check in at the front desk.  more data",
      "addressLatitude": 30.190227508544922,
      "addressLongitude": -97.77227783203125,
      "regionId": "hgi0sbrcpcffhgt1xcqgtu7bd",
      "jobDuration": 120,
      "sizeTierPricing": "{\"name\":\"tier3\",\"band\":3,\"minsqft\":3001,\"maxsqft\":4000,\"minsqm\":280,\"maxsqm\":372,\"jobhrs\":2.0,\"tierPrice\":{\"usd\":{\"payIn\":428.04},\"gbp\":{\"payIn\":283.2},\"eur\":{\"payIn\":278.4},\"jpy\":{\"payIn\":190558.0,}}}",
      "sizeTier": "tier3",
      "price": "428.04",
      "customerCurrency": "USD",
      "totalPropertySize": 3500,
      "propertySizeUnit": "SQUARE_FT",
      "contactName": "Test User",
      "contactEmail": "youremail@youremail.com",
      "contactPhone": "555-0000",
      "contactWillBeOnsite": true
    }
  }
}

Try this query in our interactive console

Show All Orders 
query orders {
  orders {
    results {
      ...JobFields
    }
  }
}

fragment JobFields on CaptureSvcsOrder {
  id
  address
  propertySizeUnit
  propertyType
  propertyTimeZone
  regionId
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
  specialRequests
}

Sample response:

{
  "data": {
    "orders": {
      "results": [
        {
          "id": "8n5y2hnet32p8k0h5buk1pu2b",
          "address": "5 holt road, 0602, 249444, SG",
          "propertySizeUnit": "SQUARE_FT",
          "propertyType": "COMMERCIAL",
          "propertyTimeZone": "Asia/Singapore",
          "regionId": "gfirz38s66k68gg2sg2pdfzhb",
          "contactName": "Winnie the Pooh",
          "contactEmail": "pooh@matterport.com",
          "contactPhone": "12",
          "contactWillBeOnsite": true,
          "specialRequests": ""
        },
        {
          "id": "4a8y39gb781dz5qaf0srrggyd",
          "address": "200 North LaSalle Street, Chicago, IL, USA",
          "propertySizeUnit": "SQUARE_FT",
          "propertyType": "RESIDENTIAL",
          "propertyTimeZone": "US/Central",
          "regionId": "kh6qmxxn7ffcf55mzc2khy7ka",
          "contactName": " Jim Bob",
          "contactEmail": "jimbob@matterport.com",
          "contactPhone": "2064550461",
          "contactWillBeOnsite": false,
          "specialRequests": ""
        },
        {
          "id": "agr36qzk217huz5qdqkd076ib",
          "address": "801 E William Cannon Dr, Austin, Travis County, TX, 78745, US",
          "propertySizeUnit": "SQUARE_FT",
          "propertyType": "RESIDENTIAL",
          "propertyTimeZone": "US/Central",
          "regionId": "hgi0sbrcpcffhgt1xcqgtu7bd",
          "contactName": "Test User",
          "contactEmail": "youremail@youremail.com",
          "contactPhone": "555-0000",
          "contactWillBeOnsite": true,
          "specialRequests": "check in at the front desk.  more data"
        }
      ]
    }
  }
}

Try this query in our interactive console

Show all Jobs 
query jobs {
  jobs {
    results {
      ...JobFields
    }
  }
}

fragment JobFields on CaptureSvcsJob {
  id
  orderId
  address
  propertySize
  propertySizeUnit
  propertyType
  propertyTimeZone
  regionId
  duration
  status
  scheduledStartTime
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
  specialRequests
  techUserId
  techAccountId
  techNotesComments
  custUserId
  custAccountId
  modelIds
  created
  modified
}

Sample response:

{
  "data": {
    "jobs": {
      "results": [
        {
          "id": "agr36qzk217huz5qdqkd076ib",
          "orderId": "agr36qzk217huz5qdqkd076ib",
          "address": "801 E William Cannon Dr, Austin, Travis County, TX, 78745, US",
          "propertySize": 3500,
          "propertySizeUnit": "SQUARE_FT",
          "propertyType": "RESIDENTIAL",
          "propertyTimeZone": "US/Central",
          "regionId": "hgi0sbrcpcffhgt1xcqgtu7bd",
          "duration": 120,
          "status": "BOOKED",
          "scheduledStartTime": "2024-12-01T17:00:00Z",
          "contactName": "Test User",
          "contactEmail": "youremail@youremail.com",
          "contactPhone": "555-0000",
          "contactWillBeOnsite": true,
          "specialRequests": "Hello Testing",
          "techUserId": "doWxoShciw9",
          "techAccountId": "UFDpezfAVoU",
          "techNotesComments": null,
          "custUserId": "zojRpo1rhox",
          "custAccountId": "1PhHdqxAn9V",
          "modelIds": null,
          "created": "2024-11-28T05:59:11Z",
          "modified": "2024-11-28T06:02:03Z"
        },
        {
          "id": "8n5y2hnet32p8k0h5buk1pu2b",
          "orderId": "8n5y2hnet32p8k0h5buk1pu2b",
          "address": "5 holt road, 0602, 249444, SG",
          "propertySize": 5000,
          "propertySizeUnit": "SQUARE_FT",
          "propertyType": "COMMERCIAL",
          "propertyTimeZone": "Asia/Singapore",
          "regionId": "gfirz38s66k68gg2sg2pdfzhb",
          "duration": 150,
          "status": "CANCELED",
          "scheduledStartTime": "2022-01-11T23:00:00Z",
          "contactName": "Shrey Mehta",
          "contactEmail": "smehta@matterport.com",
          "contactPhone": "12",
          "contactWillBeOnsite": true,
          "specialRequests": "",
          "techUserId": "C4B9tthxVvd",
          "techAccountId": "ZCuZzajnzDS",
          "techNotesComments": null,
          "custUserId": "H2YksuxAYtc",
          "custAccountId": "1PhHdqxAn9V",
          "modelIds": null,
          "created": "2022-01-10T04:34:24Z",
          "modified": "2022-01-10T04:34:55Z"
        }
      ]
    }
  }
}

Try this query in our interactive console

Patch a Job 
mutation patchJob($id: ID!, $input: CaptureSvcsJobInput!) {
  patchJob(id: $id, input: $input) {
    ...JobFields
  }
}

fragment JobFields on CaptureSvcsJob {
  id
  orderId
  address
  propertySize
  propertySizeUnit
  propertyType
  propertyTimeZone
  regionId
  duration
  status
  scheduledStartTime
  contactName
  contactEmail
  contactPhone
  contactWillBeOnsite
  specialRequests
  techUserId
  techAccountId
  techNotesComments
  custUserId
  custAccountId
  modelIds
  created
  modified
}

Variables (All valid fields shown):

{
  "id": "agr36qzk217huz5qdqkd076ib",
  "input": {
    "specialRequests": "Hello Testing",
    "contactName": "Mr. Point of Contact",
    "contactEmail": "poc@mycompany.com",
    "contactPhone": "888-736-8360",
    "specialRequests": "Wear a red shirt",
    "contactWillBeOnsite": false,
    "scheduledStartTime": "2022-01-11T23:00:00Z"
  }
}

Try this query in our interactive console

Cancel a Job 
mutation cancelJob($jobId: ID!) {
  cancelJob(id: $jobId) {
    id
  }
}

Variables:

{
  "jobId": "agr36qzk217huz5qdqkd076ib"
}

Sample response:

{
  "data": {
    "cancelJob": {
      "id": "agr36qzk217huz5qdqkd076ib"
    }
  }
}

Try this query in our interactive console

Subscriptions

We provide users with the ability to setup subscriptions, which are Webhooks, that will send a payload to a provided url whenever the following changes occur within your Capture Services bookings:

  • JOB_UPDATE
  • JOB_BOOK
  • JOB_CONFIRM
  • JOB_IN_PROGRESS
  • JOB_COMPLETE
  • JOB_CANCEL
  • PRE_ORDER_CREATE
  • PRE_ORDER_UPDATE
  • PRE_ORDER_SUBMIT
  • CAPTURE_SVCS_ORDER_CREATE
  • CAPTURE_SVCS_ORDER_UPDATE
  • CAPTURE_SVCS_ORDER_SUBMIT
Create a Subscription 
mutation newEventSubscription($input: CaptureSvcsEventSubscriptionInput!) {
  newEventSubscription(input: $input) {
    id
    created
    modified
    organizationId
    eventType
    callback {
      id
      orgId
    }
  }
}

Variables:

{
  "input": {
    "organizationId": "",
    "eventType": "JOB_CONFIRM",
    "callback": {
      "id": "",
      "orgId": "YOUR ORG SID",
      "created": "2022-01-10T04:34:24Z",
      "scheme": "https://",
      "host": "myawesomesite.com",
      "port": 443,
      "path": "myapi",
      "queryParams": [
        { "key": "arbitaryParam", "value": "true" },
        { "key": "arbitaryParam2", "value": "true" }
      ],
      "additionalHeaders": [
        { "key": "header1", "value": "true" },
        { "key": "header2", "value": "true" }
      ],
      "credType": "basic",
      "credKey": "YOURAPIKEY",
      "credSecret": "YOURAPISECRET"
    }
  }
}

Sample response:

{
  "data": {
    "cancelJob": {
      "id": "agr36qzk217huz5qdqkd076ib"
    }
  }
}

Try this query in our interactive console

Cancel a Subscription 
mutation cancelEventSubscription($id: ID!, $input: CaptureSvcsEventSubscriptionInput!) {
  patchEventSubscription(id: $id, input: $input) {
    id
    created
    modified
    organizationId
    eventType
    callback {
      id
      orgId
    }
  }
}

Variables:

{
  "input": {
    "organizationId": "",
    "eventType": "JOB_CONFIRM",
    "callback": {
      "id": "",
      "orgId": "YOUR ORG SID",
      "created": "2022-01-10T04:34:24Z",
      "scheme": "https://",
      "host": "myawesomesite.com",
      "port": 443,
      "path": "myapi",
      "queryParams": [
        { "key": "arbitaryParam", "value": "true" },
        { "key": "arbitaryParam2", "value": "true" }
      ],
      "additionalHeaders": [
        { "key": "header1", "value": "true" },
        { "key": "header2", "value": "true" }
      ],
      "credType": "basic",
      "credKey": "YOURAPIKEY",
      "credSecret": "YOURAPISECRET"
    }
  }
}

Sample response:

{
  "data": {
    "cancelJob": {
      "id": "agr36qzk217huz5qdqkd076ib"
    }
  }
}

Try this query in our interactive console