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