GraphQL request is an HTTP request with the following interface:

  Endpoint: https://partner-api.visitt.io/graphql
  Method: POST
  Headers:
    "Content-Type": "application/json"
    "Authorization": <YOUR_PARTNER_API_TOKEN>
  Body: GraphQL query JSON string

To more learn about GraphQL visit GraphQL official documentation

API Token is scope to give partner access to a single company.

Once you retrieve the token from the company visitt's account, you can start making requests with the API. You will need to pass the token to the API in the header of your requests.

Send the API token in the "Authorization" header:

"Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

A few examples on how to use the GraphQL API with curl:

  // This request fetches partner`s name
  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization: <YOUR_PARTNER_API_TOKEN>" \
    -d '{"query":"{ partner { name } }"}' \
    "https://partner-api.visitt.io/graphql"

  // This request creates a Work Order with provided description
  // and returns it`s _id
  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization: <YOUR_PARTNER_API_TOKEN>" \
    -d '{
          "query": "mutation createWorkOrder(:WorkOrderInput!) { createWorkOrder(input:) { workOrder { _id } } }",
          "variables": {
            "input": {
              "description": "Test work order from the API"
            }
          }
        }' \
    "https://partner-api.visitt.io/graphql"

How to query a record?

In order to query a record you need to pass its' _id into variables object. As an example, let's say we want to query a building with _id 89b966022061b51b9812524e.

  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization: <YOUR_PARTNER_API_TOKEN>" \
    -d '{
          "query": "query Building(: String!) { building (buildingId: ) { _id name } }",
          "variables": {
            "buildingId": "89b966022061b51b9812524e"
          }              
        }' \
    "https://partner-api.visitt.io/graphql"

Response:

  {
    "data":{
      "building":{
        "_id":"89b966022061b51b9812524e",
        "name":"Building One"
      }
    }
  }

Where to get the _id of a record from?

You can use the records list querires or get it as a part of a mutation. For example, to query all buildings and get the _id of each we can do the following request:

  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization: <YOUR_PARTNER_API_TOKEN>" \
    -d '{"query": "{ buildings { items { _id } } }" }' \
    "https://partner-api.visitt.io/graphql"

Response:

  {
    "data":{
      "buildings":{
        "items":[
          {
            "_id":"89b966022061b51b9812524e"
          },
          {
            "_id":"90d0540fd16fdd15df3f112a"
          }
        ]
      }
    }
  }

We recommend using the Apollo Studio Sandbox - a powerful web IDE for creating, running, and managing GraphQL operations. Some of the features:

• Setup the authentication once and for all
• Explore the Schema
• Create queries and mutations effortlessly
• Store frequently used requests in collections and share them
  and much more

Calls to our GraphQL API are rate limited to provide equitable access to the API for everyone and to prevent abuse. For each Partner API Token you have rate limit per query or mutation, most of them share the minimum of 100 times per each 10s window.

Automatically notify your app any time certain events occur in Visitt with incoming webhooks

Limitations

Please, consider the following Webhook API limitations:

• Only HTTPS URLs are supported
• Webhook handler should accept HTTPS POST requests with application/json body.
• Response to the webhook event should be HTTPS 200 OK, else the event is considered failed.
• Request to the webhook url has a timeout of 5 seconds, after which sending the event is considered failed.
• When the request to the webhook url failed, there will be 4 retry attempts with exponential 5 seconds delay backoff (5s, 10s, 20s, 40s).
• Webhooks urls are unique within the company.
• Up to 5 webhooks per Partner API token is allowed.
• If a Partner is inactive, Partner's webhooks will also be inactive.

How to use Webhooks API

• Add a webhook subscription to selected event types using the createWebhook mutation:

    curl \
      -X POST \
      -H "Content-Type:application/json" \
      -H "Authorization:<YOUR_PARTNER_API_TOKEN>" \
      -d '{
            "query": "mutation CreateWebhook (: WebhookInput!) { createWebhook (input: ) { webhook { _id url eventTypes active } } }",
            "variables": {
              "input": {
                  "url" : <YOUR_WEBHOOK_ENDPOINT_ADDRESS>,
                  "eventTypes": <WEBHOOK_EVENT_TYPES>,
                  "active": <IS_WEBHOOK_ACTIVE>
              }
            }
          }' \
      "https://partner-api.visitt.io/graphql"
  

• Get the full list of supported event types using the webhookEventTypes query:

  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization:<YOUR_PARTNER_API_TOKEN>" \
    -d '{
          "query": "query WebhookEventTypes { webhookEventTypes { key } }"
        }' \
    "https://partner-api.visitt.io/graphql"
  

• Update the existing webhook subscription or deactivate it using the updateWebhook mutation:

    curl \
      -X POST \
      -H "Content-Type:application/json" \
      -H "Authorization:<YOUR_PARTNER_API_TOKEN>" \
      -d '{
            "query": "mutation UpdateWebhook (: String!, : WebhookInput!) { updateWebhook (webhookId: , input: ) { webhook { _id url eventTypes active } } }",
            "variables": {
              "webhookId": <WEBHOOK_ID_TO_UPDATE>,
              "input": {
                  "url" : <YOUR_WEBHOOK_ENDPOINT_ADDRESS>,
                  "eventTypes": <WEBHOOK_EVENT_TYPES>,
                  "active": <IS_WEBHOOK_ACTIVE>
              }
            }
          }' \
      "https://partner-api.visitt.io/graphql"
  

• Get a list of all partner webhooks with partner query:

  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization:<YOUR_PARTNER_API_TOKEN>" \
    -d '{
          "query": "query Partner { partner { name webhooks { _id url eventTypes active } } }"
        }' \
    "https://partner-api.visitt.io/graphql"
  

• Access webhooks logs using the webhookLogs query:

  curl \
    -X POST \
    -H "Content-Type:application/json" \
    -H "Authorization:<YOUR_PARTNER_API_TOKEN>" \
    -d '{
          "query": "query WebhookLogs( : [WebhookLogFilter] : Int : Int ) { webhookLogs(filters: , skip: , limit: ) { items { _id eventId createdAt data } }}",
          "variables": {
            "skip": 1,
            "limit": 1,
            "filters": [
              {
                "status": {
                  "eq": "delivered"
                }
              },
              {
                "event": {
                  "eq": "workOrder.statusUpdated"
                }
              }
            ]
          }
        }' \
    "https://partner-api.visitt.io/graphql"
  

Webhook authentication

Before processing the request payload, verify the request was sent by Visitt and not an unknown party:

• Extract visitt-signature headers from the request headers. There are two values to parse from the visitt-signature header, delimited by a , (comma) character.
  • timestamp: The number of milliseconds since the epoch time at which the event was issued, prefixed by t=
  • signatureHash: The HMAC SHA256 hashed signature for the request, prefixed by v1=
• To avoid replay attacks, it's recommended to validate that the timestamp does not differ too much from the current time.
• Take the _id from the request body.
• Concatenate the timestamp and the _id, separating them with a . (dot). Should have the following string [timestamp].[_id]
• Create a hash of that string using SHA 256 algorithm with your Partner API token as a key.
• Hash the string using HMAC SHA256, with the Partner API token as the key. The expected signature will be the hex digest of the hash.
• Finally, compare signatureHash and the result hash to make sure the webhook request is valid.

A simple Webhook authentication example with ExpressJS and Crypto

app.post('/webhook', (req, res) => {
  const eventData = req.body;
  const visittSignature = req.headers['visitt-signature']; // t=1664380506499,v1=073b17a064351a1e6t7d97a60b4979329f3f3092cf38ac35ea9a0b15c8e476d8
  const [prefixedTimestamp, prefixedWebhookHmac] = visittSignature.split(',');
  const timestamp = prefixedTimestamp.replace('t=', '');
  if (Math.abs(new Date().getTime() - timestamp) > 1000 * 60 * 60 * 4) {
    // Timestamp difference is more than 4 hours, might indicate an attack attempt
  }
  const webhookHmac = prefixedWebhookHmac.replace('v1=', '');
  const hmac = crypto
    .createHmac('sha256', PARTNER_TOKEN)
    .update(`.._id}`)
    .digest('hex');
  const isValidWebhook = hmac === webhookHmac;
  if (isValidWebhook) {
    // Handle the valid webhook
  }
  res.writeHead(200);
  res.end();
});

Upload files using multipart/from-data request, and receive unique file id to attach in mutations like createWorkOrder.

• Max allowed file size is 20mb.
• Max number of files per request is 10.
• Allowed files types are images, pdf and videos with the mimetypes: image/*, video/*, application/pdf.

Endpoint

Method	Endpoint
POST	/files

Headers

Header	Value
Content-Type	multipart/form-data
Authorization	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Request structure (multipart/form-data)

Parameter	Description
files required	You can send the content of the file as binary. This is used when a file is being uploaded from the browser.

Rate Limit

The allowed rate limit is 20 requests per 60 seconds.

Example

curl
  --request POST \
  --url https://partner-api.visitt.io/files \
  --header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --header 'content-type: multipart/form-data' \
  --form 'files=@/Users/username/Desktop/file-1.png' \
  --form 'files=@/Users/username/Desktop/file-2.png'

Response

In case of an error, you will get an error code along with the error message. On successful upload, you will receive a 200 status code with uploaded file details in a JSON-encoded response body.

{
  "files": [
    {
      "fileId": "xtbisjz8sktdp57bdhso",
      "format": "png",
      "url": "https://res.cloudinary.com/gantzi/image/upload/v1653554155/xtbisjz8sktdp57bdhso.png",
      "filename": "icon-144x144",
      "bytes": 5912,
      "resourceType": "image"
    },
    {
      "fileId": "idkcuexbrmax1vlccilu",
      "format": "png",
      "url": "https://res.cloudinary.com/gantzi/image/upload/v1653554155/idkcuexbrmax1vlccilu.png",
      "filename": "visitt-logo-main",
      "bytes": 2806,
      "resourceType": "image"
    }
  ]
}

Errors

Code	Description
400	Bad Request. e.g. The request provided too many files, more then 10 files / File mimetype is not supported
401	Unauthorized. Partner Token is missing or invalid
413	Payload Too Large. The request provided files that are larger then 20mb limit
429	Too Many Requests. Rate limit exceeded

Endpoint to verify a JWT generated via App link for auto login.

Endpoint

Method	Pathname
POST	/app-link/jwt-verify

Headers

Header	Value
Content-Type	application/json
Authorization	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate Limit

The allowed rate limit is 100 requests per 60 seconds.

Example:

Request:

  curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: <JWT_TOKEN>" \
  "https://partner-api.visitt.io/app-link/jwt/verify"

Response:

  {
    "_id": "token genreated id", // unique token id
    "uid": "MgkxsnBYsYgvmYtnr",  // id of the user or contact
    "utype": "user" // the type of user in Visitt
    "email": "[email protected]", // the email address of the entity
    "phone": "+14511245298", // the phone number of the entity as international phone number, E.164 format
    "companyId": "1k312k31adsa9sjd1", // user's company id
    "source": "visitt|portal" // the source of the entity user or tenant
    "appId": "your-app"
  }

Errors

Code	Description
401	Unauthorized. Token is missing, invalid or expired

Stay up to date with the latest Partner API schema! We recommend tracking deprecated elements and schema additions using the changelog:

View All Schema Changes