Types, Examples, and Response

In the article below you will find important information about the usage of the Testinvite’s API for creating tickets. We will firstly explain structure and types of the request body, and then show some examples of calls in Postman and in different programming languages. Lastly we will describe the structure of the response body.

If you want to try API requests immediately you can check the Postman collection we have created for you. Please click here to download the Postman collection.

Types

Request body for ticket creation must consist of 3 required properties: "requester", "task", "users". Requester is an object containing properties related with authentication. Mainly you should include your organization's id and organization's private key in "auth" property of requester. Task consists only of one property: "taskId". User is an array of objects where each object represents one candidate and requires one required and different optional properties. In each object you should include "fullname" property.

On the other hand, there are optional properties such as "emailing", "callback" through which you can customize your ticket creation process. You can send e-mails to candidates from your e-mail templates included in Testinvite system or send test result data related with the ticket to the URL you define in the callback property.

In the tree view below you can see request body and its types.

  • Request body Type Information
    • requester object, required Container of organization info
      • name string, required Organization name
      • auth object, required Container of authentication properties
        • organizationId string, required Organization id
        • privateKey string, required Organization's private key
    • task object, required Container of task properties
      • taskId string, required Id of the exam
    • users array, required Container of user object's properties
      • fullname string, required Fullname of the candidate.
      • email string, optional Email address of the candidate.
      • group string, optional Group name of the candidate.
      • labels array, optional Labels to group a candidate
      • externalId string, optional Special id given by organization
      • after object, optional Container of after object's properties
        • timestamp number, required Time, ticket will be active after
        • utc number, required Time zone, in terms of Universal Time format
      • before object, optional Container of before object's properties
        • timestamp number, required Time, ticket will be active before
        • utc number, required Time zone, in terms of Universal Time format
      • extraEmails array, optional Email addresses, can be cc'd when emailing to candidate
    • emailing object, optional Container of emailing properties.
      • template string, required E-mail template's name
      • schedule number (timestamp), optional Sending date of the email.
    • callback object, optional Container for callback url data.
      • url string, required Target url where result data will automatically be sent.
      • params map (string, string), optional Query parameters for target url.

Examples

In the examples below, you can see different fetch requests with slightly different bodies. In each example, there is a request body in JSON format and a request example written in cURL. You can copy and use these examples for your own account simply by swapping in your organization's id, private key, task id etc. To create more complex tickets, you can employ your group name, labels, and etc.

Creating single ticket with only required properties

Ticket creation requests below contain only required properties and are created for one candidate.

Example body

{
  "requester": {
      "name": "Organization Name",
      "auth": {
          "organizationId": "zUH8oMYJ60As4HYP",
          "privateKey": "a8faef00-43c1-11ed-81bc-976010"
      }
  },
  "task": {
      "taskId": "tcxHArKva33C8VxCZcjy" 
  },
  "users": [
      {
        "fullname": "Candidate Name"
      }
  ]
}

cURL

curl --location --request POST 
'https://www.testinvite.com/api/v1/fatih/create-tickets'
--header 'Content-Type: application/json'
--data-raw '{
    "requester": {
        "name": "Organization Name",
        "auth": {
          "organizationId": "zUH8oMYJ60As4HYP48Zx",
          "privateKey": "76f75bd0-4315-11ed-98ad-1127beb80c0d"
        }
    },
    "task": {
      "taskId": "Qj33evNTg7IjLnao2Ux1" 
    },
    "users": [
        {
          "fullname": "Candidate Name"
        }
    ]
  }'

Creating single ticket with optional properties

Ticket creation requests below contain, in addition to required "fullname" property, optional properties in the user object such as "email", "group", and "labels".

The request also has a "callback" property, which includes a target url of your choosing. When a test session from one of these ticket ends, their result data will be sent to that url.

Example body

{
  "requester": {
      "name": "Organization Name",
      "auth": {
        "organizationId": "zUH8oMYJ60As4HYP",
        "privateKey": "a8faef00-43c1-11ed-81bc-976010"
      }
  },
  "task": {
      "taskId": "tcxHArKva33C8VxCZcjy"
  },
  "users": [
      {
        "fullname": "Candidate's Full Name",
        "email": "candidatesemail@testinvite.com",
        "group": "candidates_group",
        "labels": [
            "label1",
            "label2"
        ]
      }
  ],
  "callback": {
      "url": "https://your-domain.com/api"
  }
}

cURL

curl --location --request POST 
'https://www.testinvite.com/api/v1/fatih/create-tickets' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requester": {
        "name": "Organization Name",
        "auth": {
          "organizationId": "zUH8oMYJ60As4HYP48Zx",
          "privateKey": "76f75bd0-4315-11ed-98ad-1127beb80c0d"
        }
    },
    "task": {
        "taskId": "Qj33evNTg7IjLnao2Ux1"
    },
    "users": [
        {
          "fullname": "Candidate'\''s Full Name",
          "email": "candidatesemail@testinvite.com",
          "group": "candidates_group",
          "labels": [
              "label1",
              "label2"
          ]
        }
    ],
    "callback": {
      "url": "https://your-domain.com/api"
    }
}'

Creating multiple tickets with/out optional properties

You can employ these requests for creating multiple tickets. In examples requests are made for three candidates. First two objects of the user array have only required properties where the last object has optional properties too.

Example body

{
  "requester": {
      "name": "Organization Name",
      "auth": {
          "organizationId": "zUH8oMYJ60As4HYP",
          "privateKey": "a8faef00-43c1-11ed-81bc-976010"
      }
  },
  "task": {
      "taskId": "tcxHArKva33C8VxCZcjy" 
  },
  "users": [
      {
        "fullname": "Candidate 1 Full Name"
      },
      {
        "fullname": "Candidate 2 Full Name",
        "email": "candidatesemail@testinvite.com"
      },
      {
        "fullname": "Candidate 3 Full Name",
        "email": "candidatesemail@testinvite.com",
        "group": "candidates_group"
      }
  ]
}

cURL

curl --location --request POST 
'https://www.testinvite.com/api/v1/fatih/create-tickets' \
--header 'Content-Type: application/json' \
--data-raw '{
    "requester": {
      "name": "Organization Name",
      "auth": {
        "organizationId": "zUH8oMYJ60As4HYP48Zx",
        "privateKey": "76f75bd0-4315-11ed-98ad-1127beb80c0d"
      }
    },
    "task": {
      "taskId": "Qj33evNTg7IjLnao2Ux1" 
    },
    "users": [
       {
          "fullname": "Candidate 1 Full Name"
       },
       {
          "fullname": "Candidate 2 Full Name",
          "email": "candidatesemail@testinvite.com"
       },
       {
          "fullname": "Candidate 3 Full Name",
          "email": "candidatesemail@testinvite.com",
          "group": "candidates_group"
       }
    ]
}'

Response Body

Response body mainly consists of two parts: "kind" and "payload". Kind property takes value according to the response status. If there is no error it should be "zetok", if there is it will be "zeterror". As it contains all data about created tickets payload is the essential part of the response body.

In the payload object, you should see three properties: "credentials", "taskId", and "requestId". taskId is the id of the task and requestId is the id of the request. "credentials" is an array of objects containing important data of the created tickets. Array's lenght will be equal to ticket number created by the API call. In these objects there will be three substantial properties: "ticketId", "code", "url". ticketId is the id of the ticket to be used for fetching test results. So, you should save it to use after the exam. url is the link by which candidate can attend the assessment thus, it should be sent to the candidate in order for s/he can take the exam. With code property you can search results in the Testinvite's system.

In the tree view below you can see response body and its types.

Response Examples

You can see two response examples below for two different request. The one on the left is the response of single ticket request. In the credentials array there is one object consisting of properties mentioned above. After having this response, it is recommended that you should save "ticketId", "code", "url", and "requestId" properties to use in processes such as fetching test results via API or fetching monitoring assets.

Response for creating single ticket with required properties

{
  "kind": "zetok",
  "payload": {
   "credentials": [
    {
      "ticketId": "FgusSW9VuWUpQ39dkjfv",
      "external": {
        "id": null,
        "data": null
              },
      "code": "0a5078f0-4ab7-11ed-a8b5-6b35f9293f7e",
      "url": "https://www.testinvite.com/assessment
              /task/{taskId}?code=0a507&lang=en"
          }
      ],
    "taskId": "Qj33eUx1",
    "requestId": "MLtmTGwmnDOdr2nXRj7C"
  }
}

Response for creating multiple tickets with/out optional properties

{
  "kind": "zetok",
  "payload": {
      "credentials": [
          {
              "ticketId": "4egsNPlU8nA5F8U6bnCQ",
              "external": {
                  "id": null,
                  "data": null
              },
              "code": "4493c940-4ab7-11ed-b6f4-cde17e98e3e1",
              "url": "https://www.testinvite.com/assessment
                      /task/{taskId}?code=4493c&lang=en"
          },
          {
              "ticketId": "GRq9Vbj8EhEvF77MAZ1b",
              "external": {
                  "id": null,
                  "data": null
              },
              "code": "4493c941-4ab7-11ed-b6f4-cde17e98e3e1",
              "url": "https://www.testinvite.com/assessment
                      /task/{taskId}?code=4493c&lang=en"
          },
          {
              "ticketId": "GqEOUdGMSI5CdVrWZn8Y",
              "external": {
                  "id": null,
                  "data": null
              },
              "code": "4493f050-4ab7-11ed-b6f4-cde17e98e3e1",
              "url": "https://www.testinvite.com/assessment
                      /task/{taskId}?code=4493f&lang=en"
          }
      ],
      "taskId": "Qj33Ux1",
      "requestId": "1IGNaQYwZefCD3j8N95k"
  }
}