# HRAvatar Assessment API

Base URLs:

* <a href="https://test.hravatar.com/tx">Prod Env: https://test.hravatar.com/tx</a>

<a href="https://www.hravatar.com/terms">Terms of service</a>
Email: <a href="mailto:mike@hravatar.com">Mike Russiello, HR Avatar Inc.</a> Web: <a href="https://www.hravatar.com/contact">Mike Russiello, HR Avatar Inc.</a> 
 License: A license is not required.

# Authentication

- HTTP Authentication, scheme: basic

# Default

## POST Assessment Order Request

POST /api/v1/testorder

Used to order an assessment for a specific candidate or employee.

Base URL: https://test.hravatar.com/tx

> Body Parameters

```json
{
    "clientorderid": "hraapijsontest-5-2-2026-1",
    "packageid": {
        "assessmentid": "wYUGhp_6VEg*",
        "sendinvitationemail": 1,
        "validfrom": "2026-11-15T10:05:39.8",
        "validto": "2027-05-10T10:05:39.8"
    },
    "subjectid": {
        "firstname": "Joe",
        "lastname": "Schwartz",
        "internetemailaddress": "joe.t.schwartz@ggg.com",
        "mobilephonenumber": "(954) 740-6131",
        "langstr": "en",
        "userreferenceid": "TestTakerRef_1"
    },
    "launchoptions": {
        "redirectionurl": "https://www.google.com/",
        "resultsnotificationurl": "http://imo.hravatar.com/st/util/snoop/snooplogit.jsp",
        "emailresultsto": "mike@hravatar.com"
    }
}
```

### Params

|Name|Location|Type|Required|Title|Description|
|---|---|---|---|---|---|
|Content-Type|header|string| no ||none|
|body|body|object| yes | Assessment Order Request|none|
|» clientorderid|body|string| yes ||A unique identifier for this testing event (order). Must be unique for the third party organization. The|
|» packageid|body|object| yes ||Information about the requested assessment package.|
|»» assessmentid|body|string| yes ||The HR Avatar Id (encrypted) for the requested assessment package.|
|»» batteryid|body|string| no ||The HR Avatar Battery Id (encrypted) to be referenced by this assessment package, if any. If present, it will override the battery pointed to by the Product Record.|
|»» apitypeid|body|string| no ||Internal Use Only. The HR Avatar API Type Id (Integer) associated with this transaction.|
|»» portalid|body|string| no ||The identifier on HR Avatar (encrypted) for the specific test portal to be used.|
|»» mediadeliverymodetypeid|body|integer| no ||Mode of media delivery. Allows you to force various low bandwidth options. 0 = default (full video), 1 = audio and still images only, 2 = low bandwidth video - smaller aspect ratio in most cases.|
|»» onlineproctoringtypeid|body|integer| no ||this is the mode for online proctoring by capturing images during the assessment. Contact us for options. Default 0=No Remote Proctoring.|
|»» onlineproctoringprecheckrequired|body|integer| no ||Indicates whether a live proctor must check out the candidate before the assessment can begin. 0=No (default), 1=Yes|
|»» testtakeranonymitytypeid|body|integer| no ||Determines what personal info, if any, is collected from the candidate. 0 = default = Name, Email, 3=User ID alphanumeric, 98=Fully Anonymous|
|»» testtakeruserid|body|string| no ||Candidate UserId if testtakeranonymitytypeid=3 or username if testtakeranonymitytypeid=2|
|»» testtakeruserpassword|body|string| no ||Candidate password if testtakeranonymitytypeid=2|
|»» sendinvitationemail|body|integer| no ||A value of 1 indicates that an invitation email should be sent to the candidate if a valid email address is provided. Any other value is ignored.|
|»» sendinvitationsms|body|integer| no ||A value of 1 indicates that an invitation text message should be sent to the candidate if a valid phone number is provided. Any other value is ignored.|
|»» sendreminders|body|integer| no ||A value of 1 indicates that reminders should be sent per the Company Account default settings. Note that these are sent even if no invitation email is sent. This is used to send reminders to inline candidates who do not get an invitation but who abandon their test before finishing. Note that if an invitation is sent and this value is not included, reminders are still sent.|
|»» includescorecode|body|integer| no ||Indicates the score information to include by default when reporting status. 0 - Default - Include everything (score and any PDF reports) - same as 2 below. 1 - Include score information only - do not include any PDF 2 - Include score information including any PDF reports 4 - Do not include any score information.|
|»» duplicatecheckid|body|integer| no ||0 = default, Determines how duplicate test keys for the same candidate and same assessment package are processed. 1=Incomplete and unepired test keys only. Greater than 1=Any within X days.|
|»» duplicateignoreincomplete|body|integer| no ||0=no effect, 1=ignore existing and incomplete test keys as duplicates, 2=ignore incomplete and unscored test keys as duplicates.|
|»» timezoneid|body|integer| no ||Offest hours|
|»» thirdpartytestname|body|string| no ||The name that should be used in the PDF report for this test when the report is created.|
|»» thirdpartytesteventidentifier|body|string| no ||Unique test event identifier from the 3rd party.|
|»» thirdpartytesteventidentifiername|body|string| no ||This is the name of the  TestEventIdentifier that should appear in the report.|
|»» externalteststarturl|body|string| no ||(For externally administered [iframe] tests only) The external url at which to start the test.|
|»» externaltestwidth|body|integer| no ||(For externally administered [iframe] tests only) Width of iframe in pixels.|
|»» externaltestheight|body|integer| no ||(For externally administered [iframe] tests only) Height of iframe in pixels.|
|»» refchecktemplateid|body|string| no ||An encrypted identifier for a reference check to be performed after the test is completed.|
|»» validfrom|body|string(date-time)| no ||Beginning datetime for when the test key can be accessed by the candidate.|
|»» validto|body|string(date-time)| no ||End datetime for when the test key can be accessed by the candidate.|
|» subjectid|body|object| no ||Information about the candidate|
|»» firstname|body|string| no ||Candidate first name|
|»» lastname|body|string| no ||Candidate last name|
|»» internetemailaddress|body|string| no ||Candidate email|
|»» mobilephonenumber|body|string| no ||Candidate mobile number|
|»» langstr|body|string| no ||Candidate native or preferred language|
|»» birthdate|body|string(date)| no ||Date of birth|
|»» enthicitycode|body|string| no ||'hispanic' or 'not hispanic'|
|»» gendercode|body|integer| no ||9=Unknown, 1=Male, 2=Female, 5=non-binary, 10=prefer not to say.|
|»» nationalitycode|body|string| no ||2 digit country code|
|»» racecode|body|string| no ||White, Black or African American, Asian, American Indian or Alaskan Native, Native Hawaiian or Other Pacific Islander, or Other|
|»» countrycode|body|string| no ||2-Digit Country Code that will be used to force all percentile and other calculations to use this country instead of the IP Country or the designated account country. Useful when IP lookups appear to be erroneous.|
|»» customfield1|body|string| no ||Used to associate an optional piece of metadata with this event. Not used by HR Avatar but only included in results. Can be used as metadata to track aspects of this test event that are not used by HR Avatar.|
|»» customfield2|body|string| no ||Used to associate an optional piece of metadata with this event. Not used by HR Avatar but only included in results. Can be used as metadata to track aspects of this test event that are not used by HR Avatar.|
|»» customfield3|body|string| no ||Used to associate an optional piece of metadata with this event. Not used by HR Avatar but only included in results. Can be used as metadata to track aspects of this test event that are not used by HR Avatar.|
|»» userreferenceid|body|string| no ||A unique identifier for this candidate on the 3rd party system. Also used as User ID when needed.|
|»» suborgid|body|string| no ||The HR Avatar Sub-Organization Id for this candidate within the account encrypted.|
|»» clientuniquecustomerorganizationid|body|string| no ||A Unique Identifier for the Customer Organization on the Client System - This is the account on the client information.|
|»» clientcustomerorganizationname|body|string| no ||The Company Name for the Customer Organization on the Client System. This is required when ClientUniqueOrganizatonId is provided.|
|»» clientcustomerdefaulttestadminlangstr|body|string| no ||Required when ClientUniqueOrganizatonId is provided for the first time.  if the Default test admin language is different than the main Client account test administration language.|
|»» clientcustomerdefaultreportlangstr|body|string| no ||Required when ClientUniqueOrganizatonId is provided for the first time if the Default report language is different than the main Client account default report language.|
|» launchoptions|body|object| no ||Various settings determining how the test key is administered and how reports are distributed.|
|»» redirectionurl|body|string| no ||The URL to which the candidate is redirected when the test key is complete. Must start with http. (http://www.mycompany.com/return.html?r=wjwjwj )|
|»» resultsnotificationurl|body|string| no ||The webhook url for a POST transaction that will receive when the results are distributed. This is a URL to which the results are posted as a JSON document. Only required if the 3rd party system wants results to be pushed to them once completed.|
|»» reportcompanyname|body|string| no ||The company name to be used in any PDF reports. Will override the company name of the account.|
|»» reportcompanyimageurl|body|string| no ||A fully-qualified url for a company logo to be included in the report. Will override any image associated with the account. If a text value in curly brackets is included, only a space will be included on the report.|
|»» reportcompanyadminname|body|string| no ||The company administrator name to include in the PDF report. Will override the administrator associated with the account. If a text value in curly brackets is included, only a space will be included on the report.|
|»» reportlangstr|body|string| no ||Language to use for reporting. Defaults to account settings if not provided here.|
|»» emailresultsto|body|string| no ||Semi-colon-delimited set of email addresses to send results emails to. Defaults to account settings if not provided here.|
|»» textresultsto|body|string| no ||Semi-colon-delimited set of phone numbers to send results text messages to. Defaults to account settings if not provided here.|
|»» testadminlangstr|body|string| no ||Language to use for test administration and emails to the candidate.|
|»» omitpdfreportfromresultspost|body|integer| no ||0=do not omit (default), 1=yes omit the PDF report)|
|»» includeenglishpdfreport|body|integer| no ||0=Default (inclusion of report determined by Client Account record on HR Avatar System. 1=Do include a copy of the PDF report in english, if the primary report is in a different language and if an English version is available. This setting will override the setting in the Client Account record on the HR Avatar system.  2=Do not include a copy of the english report.|
|»» basicauthparmsforresultspost|body|string| no ||string with username and password, delimited by a semi colon (not Base64 encoded). This is the username and password for posting back to the 3rd party server in the HTTP Basic Auth line. The HR Avatar system will combine these and base64 encode them and include them in the header of the POST when pushing a POST back to a 3rd party server (using ResultsNotificationUrl)|
|»» errorredirectionurl|body|string| no ||Url to which the candidate is directed in case of an error during testing. Must start with http.|
|»» reportmediaviewurl|body|string| no ||This is a full domain (example: https://yourdomain.com/yourmediaviewservlet) that will be inserted into video and audio urls contained in pdf reports along with 2 request parameters: type (integer value) and uid (alphanumeric value) which will be appended to the query parameters in the url, if any. The URL that will be embedded in the PDF is https://yourdomain.com/yourmediaviewservlet?type=N&uufid=XXXXXXXXX These two parameters can be recovered by the web resource and used to access the HR Avatar MediaView API via GET to obtain a direct url and other information (uri,width,height,contenttype,duration) via a JSON response. See the integration guide (https://www.hravatar.com/api) for more details about the MediaView API.|
|»» authuserinternetemailaddress|body|string| no ||Email address of the person to be used as the initiator of this TestKey and Reference Check (if there is one).|
|»» collectresume|body|integer| no ||0 = (default) Do not collect a resume during the test., 1 = Collect (optional), 2 = Collect (required).|
|» raters|body|[object]| no ||Used only for Test keys that initiate Reference Checks only. This is where you can specify references to be included within the created reference check.|
|»» identifier|body|string| yes ||Must be a unique identifier for this rater within this Reference Check|
|»» firstname|body|string| yes ||none|
|»» lastname|body|string| yes ||none|
|»» internetemailaddress|body|string| no ||Rater email. Optional but either email or mobile phone number are required.|
|»» mobilephonenumber|body|string| no ||Rater mobile number. Optional but either email or mobile phone number are required.|
|»» companyname|body|string| no ||Rater's company name when he or she worked with the candidate.|
|»» candidateduties|body|string| no ||The duties performed by the candidate when they worked with the Rater.|
|»» roletypeid|body|integer| no ||0=not known, 5=manager, 10=supervisor, 15=peer, 20=subordinate|
|»» fromdate|body|string(date)| no ||Start date of when the Rater worked with the Candidate.|
|»» todate|body|string(date)| no ||End date of when the Rater worked with the Candidate.|
|»» send|body|integer| no ||0=Do not send invitation (default), 1=Send an invitation via email, text message, or both.|

> Body Json Schema

```json
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Assessment Order Request",
    "type": "object",
    "description": "This transaction is used to order the administration of an 'assessment package' to a single 'candidate'. An 'assessment package' is one or more 'tests' on the HR Avatar system. A 'test' is a standalone object that can be scored individually. When an 'assessment package' has more than one 'test' it uses a 'test battery' to group the 'tests' together. If successful, the transaction will produce a 'Test Key' which is a URL that can be used to take all tests associated with the assessment package in a single sitting. When the 'Test Key' is complete it is scored and results are either pushed to the specified webhook url or pulled by a status request transaction.  Most fields are optional.",
    "properties": {
        "clientorderid": {
            "type": "string",
            "description": "A unique identifier for this testing event (order). Must be unique for the third party organization. The "
        },
        "packageid": {
            "type": "object",
            "description": "Information about the requested assessment package.",
            "properties": {
                "assessmentid": {
                    "type": "string",
                    "description": "The HR Avatar Id (encrypted) for the requested assessment package."
                },
                "validfrom": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Beginning datetime for when the test key can be accessed by the candidate."
                },
                "validto": {
                    "type": "string",
                    "format": "date-time",
                    "description": "End datetime for when the test key can be accessed by the candidate."
                },
                "sendinvitationemail": {
                    "type": "integer",
                    "description": "A value of 1 indicates that an invitation email should be sent to the candidate if a valid email address is provided. Any other value is ignored."
                },
                "sendinvitationsms": {
                    "type": "integer",
                    "description": "A value of 1 indicates that an invitation text message should be sent to the candidate if a valid phone number is provided. Any other value is ignored."
                },
                "sendreminders": {
                    "type": "integer",
                    "description": "A value of 1 indicates that reminders should be sent per the Company Account default settings. Note that these are sent even if no invitation email is sent. This is used to send reminders to inline candidates who do not get an invitation but who abandon their test before finishing. Note that if an invitation is sent and this value is not included, reminders are still sent."
                },
                "includescorecode": {
                    "type": "integer",
                    "description": "Indicates the score information to include by default when reporting status. 0 - Default - Include everything (score and any PDF reports) - same as 2 below. 1 - Include score information only - do not include any PDF 2 - Include score information including any PDF reports 4 - Do not include any score information."
                },
                "testtakeruserid": {
                    "type": "string",
                    "description": "Candidate UserId if testtakeranonymitytypeid=3 or username if testtakeranonymitytypeid=2"
                },
                "portalid": {
                    "type": "string",
                    "description": "The identifier on HR Avatar (encrypted) for the specific test portal to be used."
                },
                "onlineproctoringtypeid": {
                    "type": "integer",
                    "description": "this is the mode for online proctoring by capturing images during the assessment. Contact us for options. Default 0=No Remote Proctoring."
                },
                "onlineproctoringprecheckrequired": {
                    "type": "integer",
                    "description": "Indicates whether a live proctor must check out the candidate before the assessment can begin. 0=No (default), 1=Yes"
                },
                "mediadeliverymodetypeid": {
                    "type": "integer",
                    "description": "Mode of media delivery. Allows you to force various low bandwidth options. 0 = default (full video), 1 = audio and still images only, 2 = low bandwidth video - smaller aspect ratio in most cases."
                },
                "testtakeranonymitytypeid": {
                    "type": "integer",
                    "description": "Determines what personal info, if any, is collected from the candidate. 0 = default = Name, Email, 3=User ID alphanumeric, 98=Fully Anonymous"
                },
                "testtakeruserpassword": {
                    "type": "string",
                    "description": "Candidate password if testtakeranonymitytypeid=2"
                },
                "duplicatecheckid": {
                    "type": "integer",
                    "description": "0 = default, Determines how duplicate test keys for the same candidate and same assessment package are processed. 1=Incomplete and unepired test keys only. Greater than 1=Any within X days."
                },
                "duplicateignoreincomplete": {
                    "type": "integer",
                    "description": "0=no effect, 1=ignore existing and incomplete test keys as duplicates, 2=ignore incomplete and unscored test keys as duplicates."
                },
                "thirdpartytestname": {
                    "type": "string",
                    "description": "The name that should be used in the PDF report for this test when the report is created."
                },
                "thirdpartytesteventidentifier": {
                    "type": "string",
                    "description": "Unique test event identifier from the 3rd party."
                },
                "thirdpartytesteventidentifiername": {
                    "type": "string",
                    "description": "This is the name of the  TestEventIdentifier that should appear in the report."
                },
                "externaltestwidth": {
                    "type": "integer",
                    "description": "(For externally administered [iframe] tests only) Width of iframe in pixels."
                },
                "externaltestheight": {
                    "type": "integer",
                    "description": "(For externally administered [iframe] tests only) Height of iframe in pixels."
                },
                "batteryid": {
                    "type": "string",
                    "description": "The HR Avatar Battery Id (encrypted) to be referenced by this assessment package, if any. If present, it will override the battery pointed to by the Product Record."
                },
                "apitypeid": {
                    "type": "integer",
                    "description": "Internal HR Avatar flag to indicate use of a wrapper to support directly connected client systems. Default is 0"
                },
                "refchecktemplateid": {
                    "type": "string",
                    "description": "An encrypted identifier for a reference check to be performed after the test is completed. This is only for requests that are BOTH a test followed by a reference check. If the request is for a reference check only, then the templateid is embedded in the assessmentid\n"
                },
                "externalteststarturl": {
                    "type": "string",
                    "description": "(For externally administered [iframe] tests only) The external url at which to start the test."
                },
                "timezoneoffsetminutes": {
                    "type": "integer",
                    "description": "Offest minutes"
                }
            },
            "required": [
                "assessmentid"
            ],
            "x-apidog-orders": [
                "assessmentid",
                "validfrom",
                "validto",
                "sendinvitationemail",
                "sendinvitationsms",
                "sendreminders",
                "includescorecode",
                "testtakeruserid",
                "portalid",
                "onlineproctoringtypeid",
                "onlineproctoringprecheckrequired",
                "mediadeliverymodetypeid",
                "testtakeranonymitytypeid",
                "testtakeruserpassword",
                "duplicatecheckid",
                "duplicateignoreincomplete",
                "timezoneoffsetminutes",
                "thirdpartytestname",
                "thirdpartytesteventidentifier",
                "thirdpartytesteventidentifiername",
                "externalteststarturl",
                "externaltestwidth",
                "externaltestheight",
                "refchecktemplateid",
                "batteryid",
                "apitypeid"
            ]
        },
        "subjectid": {
            "type": "object",
            "description": "Information about the candidate",
            "properties": {
                "firstname": {
                    "type": "string",
                    "description": "Candidate first name"
                },
                "lastname": {
                    "type": "string",
                    "description": "Candidate last name"
                },
                "userreferenceid": {
                    "type": "string",
                    "description": "A unique identifier for this candidate on the 3rd party system. Also used as User ID when needed."
                },
                "internetemailaddress": {
                    "type": "string",
                    "description": "Candidate email"
                },
                "mobilephonenumber": {
                    "type": "string",
                    "description": "Candidate mobile number"
                },
                "langstr": {
                    "type": "string",
                    "description": "Candidate native or preferred language"
                },
                "birthdate": {
                    "type": "string",
                    "format": "date",
                    "description": "Date of birth"
                },
                "enthicitycode": {
                    "type": "string",
                    "description": "'hispanic' or 'not hispanic'"
                },
                "gendercode": {
                    "type": "integer",
                    "description": "9=Unknown, 1=Male, 2=Female, 5=non-binary, 10=prefer not to say."
                },
                "nationalitycode": {
                    "type": "string",
                    "description": "2 digit country code"
                },
                "racecode": {
                    "type": "string",
                    "description": "White, Black or African American, Asian, American Indian or Alaskan Native, Native Hawaiian or Other Pacific Islander, or Other"
                },
                "countrycode": {
                    "type": "string",
                    "description": "2-Digit Country Code that will be used to force all percentile and other calculations to use this country instead of the IP Country or the designated account country. Useful when IP lookups appear to be erroneous."
                },
                "customfield1": {
                    "type": "string",
                    "description": "Used to associate an optional piece of metadata with this event. Not used by HR Avatar but only included in results. Can be used as metadata to track aspects of this test event that are not used by HR Avatar."
                },
                "customfield2": {
                    "type": "string",
                    "description": "Used to associate an optional piece of metadata with this event. Not used by HR Avatar but only included in results. Can be used as metadata to track aspects of this test event that are not used by HR Avatar."
                },
                "customfield3": {
                    "type": "string",
                    "description": "Used to associate an optional piece of metadata with this event. Not used by HR Avatar but only included in results. Can be used as metadata to track aspects of this test event that are not used by HR Avatar."
                },
                "suborgid": {
                    "type": "string",
                    "description": "The HR Avatar Sub-Organization Id for this candidate within the account encrypted. "
                },
                "clientuniquecustomerorganizationid": {
                    "type": "string",
                    "description": "A Unique Identifier for the Customer Organization on the Client System - This is the account on the client information."
                },
                "clientcustomerorganizationname": {
                    "type": "string",
                    "description": "The Company Name for the Customer Organization on the Client System. This is required when ClientUniqueOrganizatonId is provided."
                },
                "clientcustomerdefaulttestadminlangstr": {
                    "type": "string",
                    "description": "Required when ClientUniqueOrganizatonId is provided for the first time.  if the Default test admin language is different than the main Client account test administration language."
                },
                "clientcustomerdefaultreportlangstr": {
                    "type": "string",
                    "description": "Required when ClientUniqueOrganizatonId is provided for the first time if the Default report language is different than the main Client account default report language."
                }
            },
            "x-apidog-orders": [
                "firstname",
                "lastname",
                "userreferenceid",
                "internetemailaddress",
                "mobilephonenumber",
                "langstr",
                "birthdate",
                "enthicitycode",
                "gendercode",
                "nationalitycode",
                "racecode",
                "countrycode",
                "customfield1",
                "customfield2",
                "customfield3",
                "suborgid",
                "clientuniquecustomerorganizationid",
                "clientcustomerorganizationname",
                "clientcustomerdefaulttestadminlangstr",
                "clientcustomerdefaultreportlangstr"
            ]
        },
        "launchoptions": {
            "type": "object",
            "description": "Various settings determining how the test key is administered and how reports are distributed.",
            "properties": {
                "redirectionurl": {
                    "type": "string",
                    "description": "The URL to which the candidate is redirected when the test key is complete. Must start with http. (http://www.mycompany.com/return.html?r=wjwjwj )"
                },
                "resultsnotificationurl": {
                    "type": "string",
                    "description": "The webhook url for a POST transaction that will receive when the results are distributed. This is a URL to which the results are posted as a JSON document. Only required if the 3rd party system wants results to be pushed to them once completed."
                },
                "emailresultsto": {
                    "type": "string",
                    "description": "Semi-colon-delimited set of email addresses to send results emails to. Defaults to account settings if not provided here."
                },
                "textresultsto": {
                    "type": "string",
                    "description": "Semi-colon-delimited set of phone numbers to send results text messages to. Defaults to account settings if not provided here."
                },
                "reportcompanyname": {
                    "type": "string",
                    "description": "The company name to be used in any PDF reports. Will override the company name of the account."
                },
                "reportcompanyimageurl": {
                    "type": "string",
                    "description": "A fully-qualified url for a company logo to be included in the report. Will override any image associated with the account. If a text value in curly brackets is included, only a space will be included on the report."
                },
                "reportcompanyadminname": {
                    "type": "string",
                    "description": "The company administrator name to include in the PDF report. Will override the administrator associated with the account. If a text value in curly brackets is included, only a space will be included on the report."
                },
                "reportlangstr": {
                    "type": "string",
                    "description": "Language to use for reporting. Defaults to account settings if not provided here."
                },
                "testadminlangstr": {
                    "type": "string",
                    "description": "Language to use for test administration and emails to the candidate."
                },
                "omitpdfreportfromresultspost": {
                    "type": "integer",
                    "description": "0=do not omit (default), 1=yes omit the PDF report)"
                },
                "includeenglishpdfreport": {
                    "type": "integer",
                    "description": "0=Default (inclusion of report determined by Client Account record on HR Avatar System. 1=Do include a copy of the PDF report in english, if the primary report is in a different language and if an English version is available. This setting will override the setting in the Client Account record on the HR Avatar system.  2=Do not include a copy of the english report."
                },
                "basicauthparmsforresultspost": {
                    "type": "string",
                    "description": "string with username and password, delimited by a semi colon (not Base64 encoded). This is the username and password for posting back to the 3rd party server in the HTTP Basic Auth line. The HR Avatar system will combine these and base64 encode them and include them in the header of the POST when pushing a POST back to a 3rd party server (using ResultsNotificationUrl)"
                },
                "errorredirectionurl": {
                    "type": "string",
                    "description": "Url to which the candidate is directed in case of an error during testing. Must start with http."
                },
                "reportmediaviewurl": {
                    "type": "string",
                    "description": "This is a full domain (example: https://yourdomain.com/yourmediaviewservlet) that will be inserted into video and audio urls contained in pdf reports along with 2 request parameters: type (integer value) and uid (alphanumeric value) which will be appended to the query parameters in the url, if any. The URL that will be embedded in the PDF is https://yourdomain.com/yourmediaviewservlet?type=N&uufid=XXXXXXXXX These two parameters can be recovered by the web resource and used to access the HR Avatar MediaView API via GET to obtain a direct url and other information (uri,width,height,contenttype,duration) via a JSON response. See the integration guide (https://www.hravatar.com/api) for more details about the MediaView API."
                },
                "authuserinternetemailaddress ": {
                    "type": "string",
                    "description": "Email address of the person to be used as the initiator of this TestKey and Reference Check (if there is one)."
                },
                "collectresume ": {
                    "type": "integer",
                    "description": "0 = (default) Do not collect a resume during the test., 1 = Collect (optional), 2 = Collect (required)."
                },
                "internetspeedtest": {
                    "type": "integer",
                    "description": "0 = (default) Do not perform an internet speed test during the test., 1 = perform test."
                },
                "usessandbox": {
                    "type": "integer",
                    "description": "1 = indicates that this request is associated with a ats sandbox account or the calling api sandbox environment (if using a middleware wrapper). Default is 0."
                }
            },
            "x-apidog-orders": [
                "authuserinternetemailaddress ",
                "basicauthparmsforresultspost",
                "collectresume ",
                "emailresultsto",
                "errorredirectionurl",
                "includeenglishpdfreport",
                "internetspeedtest",
                "omitpdfreportfromresultspost",
                "redirectionurl",
                "reportcompanyname",
                "reportcompanyimageurl",
                "reportcompanyadminname",
                "reportlangstr",
                "reportmediaviewurl",
                "resultsnotificationurl",
                "testadminlangstr",
                "textresultsto",
                "usessandbox"
            ]
        },
        "raters": {
            "type": "array",
            "description": "Used only for Test keys that initiate Reference Checks only. This is where you can specify references to be included within the created reference check.",
            "items": {
                "type": "object",
                "description": "Information about a specific reference check rater",
                "properties": {
                    "identifier": {
                        "type": "string",
                        "description": "Must be a unique identifier for this rater within this Reference Check. If not provided for a rater object, this value is generated by HR Avatar."
                    },
                    "firstname": {
                        "type": "string",
                        "description": ""
                    },
                    "lastname": {
                        "type": "string",
                        "description": ""
                    },
                    "internetemailaddress": {
                        "type": "string",
                        "description": "Rater email. Optional but either email or mobile phone number are required."
                    },
                    "mobilephonenumber": {
                        "type": "string",
                        "description": "Rater mobile number. Optional but either email or mobile phone number are required."
                    },
                    "companyname": {
                        "type": "string",
                        "description": "Rater's company name when he or she worked with the candidate."
                    },
                    "candidateduties": {
                        "type": "string",
                        "description": "The duties performed by the candidate when they worked with the Rater."
                    },
                    "roletypeid": {
                        "type": "integer",
                        "description": "0=not known, 5=manager, 10=supervisor, 15=peer, 20=subordinate"
                    },
                    "fromdate": {
                        "type": "string",
                        "format": "date",
                        "description": "Start date of when the Rater worked with the Candidate."
                    },
                    "todate": {
                        "type": "string",
                        "format": "date",
                        "description": "End date of when the Rater worked with the Candidate."
                    },
                    "send": {
                        "type": "integer",
                        "description": "0=Do not send invitation (default), 1=Send an invitation via email, text message, or both."
                    }
                },
                "required": [
                    "firstname",
                    "lastname"
                ],
                "x-apidog-orders": [
                    "identifier",
                    "firstname",
                    "lastname",
                    "internetemailaddress",
                    "mobilephonenumber",
                    "companyname",
                    "candidateduties",
                    "roletypeid",
                    "fromdate",
                    "todate",
                    "send"
                ]
            }
        }
    },
    "required": [
        "clientorderid",
        "packageid"
    ],
    "x-apidog-orders": [
        "clientorderid",
        "packageid",
        "subjectid",
        "launchoptions",
        "raters"
    ]
}
```

> Response Examples

> 200 Response

```json
{
    "clientorderid": "hraapijsontest-5-2-2026-1",
    "accesspoint": {
        "assessmentid": "ju-yUjop5HM*",
        "validfrom": "2026-05-01T10:33:39.0767758",
        "validto": "2027-09-16T13:08:19.877",
        "starturl": "https://st3/tt/tk/942/3/AYF3MWX7YBZE"
    },
    "requestinfo": {
        "status": "Acknowledged",
        "statusdate": "2026-05-01T10:33:39.0712491"
    },
    "userarea": {
        "testkey": "LKy0sI8dX38*",
        "assessmentstatusdescription": "Started",
        "assessmentstatustypeid": 1
    }
}
```

### Responses

|HTTP Status Code |Meaning|Description|Data schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|none|Inline|

### Responses Data Schema

HTTP Status Code **200**

*Assessment Order Response*

|Name|Type|Required|Restrictions|Title|description|
|---|---|---|---|---|---|
|» clientorderid|string|true|none||A unique identifier for this assessment event (order). Must be unique for the third party organization.|
|» accesspoint|object|false|none||Information about the requested assessment package.|
|»» assessmentid|string|true|none||The HR Avatar Product Id (encrypted)  for this assessment.|
|»» validfrom|string(date-time)|true|none||Beginning datetime for when the test can be started.|
|»» validto|string(date-time)|true|none||End datetime for when the test can be started, after which the test key expires.|
|»» starturl|string|true|none||This is the URL that will start the test.|
|» rateraccesspoints|[object]|false|none||Used only for Reference Checks only.|
|»» identifier|string|true|none||Must be a unique identifier for this rater within this Reference Check|
|»» firstname|string|true|none||none|
|»» lastname|string|true|none||none|
|»» internetemailaddress|string|false|none||Rater email. Optional but either email or mobile phone number are required.|
|»» mobilephonenumber|string|false|none||Rater mobile number. Optional but either email or mobile phone number are required.|
|»» starturl|string|true|none||The URL at which the rater can start their reference check.|
|» requestinfo|object|true|none||Information about the status of the order request.|
|»» status|string|true|none||Acknowledged or Error|
|»» errorcode|integer|false|none||0=No Error (success), 1=Insufficient or erroneous request information, 2= Unknown system error.|
|»» errordetails|string|false|none||If status is error, the error details are here|
|»» statusdate|string(date-time)|true|none||The date time the assessment order request was processed.|
|» userarea|object|false|none||These are proprietary fields used by the HR Avatar System. Only included if order request succeeded.|
|»» testkey|string|false|none||A permenant unique identifier for this testing event on the the HR Avatar system.|
|»» assessmentstatustypeid|integer|false|none||Unstarted tests use a status identifer of 0. Completed tests used a status identifier of 100. Contact HR Avatar for a complete list.|
|»» thirdpartycookiesrequired|integer|false|none||Indicates that third-party cookies are required if running the test inside an HTML Frame. If not running inside a Frame this value can be ignored. 0=NOT required. 1=Required.|
|»» assessmentstatusdescription|string|false|none||Name for the assessment status|
|»» clientcustomeraccountid|string|false|none||Unique ID of the client account that was created on HR Avatar if the request had a new clientuniquecustomerorganizatonid.|
|»» clientcustomeraccountname|string|false|none||Name of the client account that was created on HR Avatar if the request had a new clientuniquecustomerorganizatonid.|

# Data Json Schema

```json
{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Assessment Order Response",
    "description": "Defines the response to an assessment order request. For successful requests, a Test Key is generated and information about the test key is presented here. Important information includes the starturl and validity dates.",
    "type": "object",
    "properties": {
        "clientorderid": {
            "type": "string",
            "description": "A unique identifier for this assessment event (order). Must be unique for the third party organization."
        },
        "accesspoint": {
            "type": "object",
            "description": "Information about the requested assessment package.",
            "properties": {
                "assessmentid": {
                    "type": "string",
                    "description": "The HR Avatar Product Id (encrypted)  for this assessment."
                },
                "validfrom": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Beginning datetime for when the test can be started."
                },
                "validto": {
                    "type": "string",
                    "format": "date-time",
                    "description": "End datetime for when the test can be started, after which the test key expires."
                },
                "starturl": {
                    "type": "string",
                    "description": "This is the URL that will start the test. This is provided only if the Candidate portion is not completed.\n"
                }
            },
            "required": [
                "assessmentid",
                "validfrom",
                "validto"
            ],
            "x-apidog-orders": [
                "assessmentid",
                "validfrom",
                "validto",
                "starturl"
            ]
        },
        "rateraccesspoints": {
            "type": "array",
            "description": "Used only for Reference Checks only.",
            "items": {
                "type": "object",
                "description": "Information about a specific reference check rater",
                "properties": {
                    "identifier": {
                        "type": "string",
                        "description": "Must be a unique identifier for this rater within this Reference Check"
                    },
                    "firstname": {
                        "type": "string",
                        "description": ""
                    },
                    "lastname": {
                        "type": "string",
                        "description": ""
                    },
                    "internetemailaddress": {
                        "type": "string",
                        "description": "Rater email. Optional but either email or mobile phone number are required."
                    },
                    "mobilephonenumber": {
                        "type": "string",
                        "description": "Rater mobile number. Optional but either email or mobile phone number are required."
                    },
                    "starturl": {
                        "type": "string",
                        "description": "The URL at which the rater can start their reference check."
                    }
                },
                "required": [
                    "identifier"
                ],
                "x-apidog-orders": [
                    "identifier",
                    "firstname",
                    "lastname",
                    "internetemailaddress",
                    "mobilephonenumber",
                    "starturl"
                ]
            }
        },
        "requestinfo": {
            "type": "object",
            "description": "Information about the status of the order request.",
            "properties": {
                "status": {
                    "type": "string",
                    "description": "Acknowledged or Error"
                },
                "errorcode": {
                    "type": "integer",
                    "description": "0=No Error (success), 1=Insufficient or erroneous request information, 2= Unknown system error."
                },
                "errordetails": {
                    "type": "string",
                    "description": "If status is error, the error details are here"
                },
                "statusdate": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The date time the assessment order request was processed."
                }
            },
            "required": [
                "status",
                "statusdate"
            ],
            "x-apidog-orders": [
                "status",
                "errorcode",
                "errordetails",
                "statusdate"
            ]
        },
        "userarea": {
            "type": "object",
            "description": "These are proprietary fields used by the HR Avatar System. Only included if order request succeeded.",
            "properties": {
                "testkey": {
                    "type": "string",
                    "description": "A permenant unique identifier for this testing event on the the HR Avatar system."
                },
                "assessmentstatustypeid": {
                    "type": "integer",
                    "description": "Unstarted tests use a status identifer of 0. Completed tests used a status identifier of 100. Contact HR Avatar for a complete list."
                },
                "thirdpartycookiesrequired": {
                    "type": "integer",
                    "description": "Indicates that third-party cookies are required if running the test inside an HTML Frame. If not running inside a Frame this value can be ignored. 0=NOT required. 1=Required."
                },
                "assessmentstatusdescription": {
                    "type": "string",
                    "description": "Name for the assessment status"
                },
                "clientcustomeraccountid": {
                    "type": "string",
                    "description": "Unique ID of the client account that was created on HR Avatar if the request had a new clientuniquecustomerorganizatonid."
                },
                "clientcustomeraccountname": {
                    "type": "string",
                    "description": "Name of the client account that was created on HR Avatar if the request had a new clientuniquecustomerorganizatonid."
                },
                "accesskey": {
                    "type": "string",
                    "description": "A second unique identifier for the testkey which is used in launch URLs.\n"
                }
            },
            "x-apidog-orders": [
                "testkey",
                "accesskey",
                "assessmentstatustypeid",
                "thirdpartycookiesrequired",
                "assessmentstatusdescription",
                "clientcustomeraccountid",
                "clientcustomeraccountname"
            ]
        }
    },
    "required": [
        "clientorderid",
        "requestinfo"
    ],
    "x-apidog-orders": [
        "clientorderid",
        "accesspoint",
        "rateraccesspoints",
        "requestinfo",
        "userarea"
    ]
}
```
