API Documentation for Creating Tickets

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