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
      • 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
      • 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
    • 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
        You can get json format of ticket's test results to the URL you define.
      • params
        map (string, string), optional
        You can define URL more precisely.

Examples

In the examples below, you can see 3 different ticket creation requests. The example on the left is created in POSTMAN, and the right one is created according to cURL. You can use these examples simply by using your organization's id, private key, and taskId. 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". Plus, they have a "callback" property used for sending test results when the session ends.

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",
              "label3"
          ]
      }
  ],
  "callback": {
      "url": "https://www.testinvite.com/api/v1/fatih/test-result-callback"
  }
}
          

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",
                "label3"
            ]
        }
    ],
    "callback": {
        "url": "https://www.testinvite.com/api/v1/fatih/test-result-callback"
    }
}'
          

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"
                  },
                  {
                      "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"
                    },
                    {
                        "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 body
    Type
    Information
    • kind
      string
      Kind of response according to status
    • payload
      object
      Container of ticket data
      • taskId
        string
        Id of the task.
      • requestId
        string
        Id of the request.
      • credentials
        array
        Array of objects for ticket data
        • ticketId
          string
          Id of the ticket created. You should save this id as you will need it for test results query.
        • code
          string
          Special code of the ticket. You should save it to be able to use it.
        • url
          string
          Access URL of the ticket by which candidate can take the assessment. You should save it and send it to the candidate.
        • external
          object
          Container of external data
          • id
            string
            Id of the candidate defined by your company in the request. (Will be null if not used)
          • data
            object
            Container of the properties defined for the candidate by your company. (Will be null if not used)

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"
  }
}