SendReport Method - Berke Assessment API

Sends a PDF report via email. Returns an XML or JSON document describing where the invitation was sent.

See the GetReportForJob method to download a PDF report.

Parameter	Value
apiToken	Required. 1-50 characters. Case-sensitive. Visit Settings \| API:Security to change your API token (Berke login required). Your API token is a server-side authentication value. Do not embed it in client-side Javascript or submit it to Berke via an insecure connection.
username	Optional. Null or 1-50 characters. Your API Token is mapped to a default user. Use this field to change from the default API user to a specific user. The user must exist in your Berke account and is active. Null defaults to default API user. Visit Settings \| API:Security to change your default API user (Berke login required).
sourceCandidateId	Required. 1-50 characters. Not case-sensitive. Source identifier of the participant to update. Existing SourceCandidateId values can be seen and/or modified in the Berke Assessment site by clicking the Optional Settings button on the Update Assessment User page.
sourceJobId	Optional. 0-50 characters. If null, the assessment's primary job will be selected. If provided, SourceJobId must be assigned to a Berke job via the Settings link's API \| Job Assignments (Berke login required) option. You can retrieve your sourceJobId values with the GetJobs method.
emailAddress	Optional. If not null, up to 5 unique addresses, max 500 characters. Separate each address with a comma. All addresses must be well-formed and valid. If null, then the report will be emailed to the hiring manager associated with the assessment.
audienceTypeId	Optional. Null or 0 or 1. Null and 0 select [Hiring Manager]. 1 selects [Participant].
reportTypeId	Optional. Null or 0 to 3. Null and 0 select the default report for the audience, 1 selects [Job Fit Report], 2 selects [Spotlight Report], and 3 selects [Participant Report].
emailMessage	Optional. Null or 1-1000 characters. To avoid spam blockers, do not use exclamation points or PHRASES IN CAPS. All HTML tags will be converted to static entities.
fromFullName	Optional. Null or 1-100 characters. If null, the full name of the participant's hiring manager will be used.
replyToAddress	Optional. Null or 1-100 characters. If provided, must be a well-formed email address. If null, the email address of the participant's hiring manager will be used.
formatOutput	Optional. Defaults to first value in list if not supplied. This value sets format in which to return the results of the method. All formats return the same data and hierarchical layout.

<?xml version="1.0" encoding="utf-16"?>
<berkeResponse status="ok" responseCode="200">
  <assessment sourceCandidateId="[sourceCandidateId]" sourceJobId="[sourceJobId]" action="Report emailed to [candidate@candidate.domain]" />
</berkeResponse>

{
  "assessment": {
    "sourceCandidateId": "[sourceCandidateId]",
    "sourceJobId": "[sourceJobId]",
    "action": "Report emailed to [candidate@candidate.domain]"
  },
  "status": "ok",
  "response": null,
  "responseCode": "200"
}

<?xml version="1.0" encoding="utf-16"?>
<berkeResponse status="[!=ok]" response="[Error Message], [Parameter]=[[ParameterValue]]" responseCode="[!=200]" />

{
  "status": "[!=ok]",
  "response": "[Error Message], [Parameter]=[[ParameterValue]]",
  "responseCode": "[!=200]"
}

Successful Example Response
Success [200]	The sourceCandidateId attribute is the assessment you requested. If you passed in newSourceCandidateId, the new value will be reflected here.

Handing Errors

All API requests include two extended HTTP headers in the response:

X-Response-Code
Contains the HTTP status code (400, 200, etc.) and a Berke status code.
The format is [Http Status Code].[Berke Status Code].
X-Response-Message
Contains a message describing the X-Response-Code header.

If your request was successful, X-Response-Code will be 200.0. If the Berke response code is 1000 or greater, then an error occurred. For example, 403.1003 tells you that there was a HTTP 403 error (Forbidden). The 1003 Berke status code tells you the API key is invalid.

When an error occurs, further information can be found in the X-Response-Message header. For example, X-Response-Message will return API key '[API.Key.Sent.To.Berke]' is invalid or inactive if the API key was not authenticated.

The most common errors returned for this method are listed below.

Status Code	Failed Example Responses
Email Required [403.1025]	Your request failed. Error 1025 The emailAddress field is required.
Invalid Email Address [403.1024]	Your request failed. Error 1024 The email address you supplied is missing or not well formed. All addresses must pass this regular expression: ^(?:\s)[a-zA-Z0-9~#%$&/'`!_.+-]+@[a-zA-Z0-9-_]+\.[a-zA-Z0-9-.]{2,}(?:\s*)$
Assessment Inactive [403.1014]	Your request failed. The assessment you requested is no longer available. Error 1014 The assessment you requested has been deleted or inactivated.
Job Inactive [403.1015]	Your request failed. The job you requested is no longer available. Error 1015 The job you requested has been deleted or inactivated.
Assessment In Progress [403.1017]	Your request failed. The assessment you requested is not complete. Error 1017 The assessment you requested is not complete.
SourceJobId not found [403.1019]	Your request failed. SourceJobId not found. Error 1019 The SourceJobId you passed in was not found. Visit your Job Assignments (Berke login required) to correct.
SourceCandidateId not found [403.1020]	Your request failed. SourceCandidateId not found. Error 1020 The SourceCandidateId value you passed in was not found.
Not Enough Assessment Data To Create Report for SourceJobId [403.1021]	Your request failed. SourceJobId [###] cannot be used to generate a report for the requested SourceCandidateId. The assessment does not contain enough data. Assessment is only [##]% complete against the [Requested Job Name]. Remaining sections include [Uncaptured Assessment Sections Required By Requested Job]. Completed sections include [Captured Assessment Sections Used By Requested Job], SourceJobId=[[###]] Error 1021 There was not enough assessment data captured for the SourceCandidateId to create a report using the requested SourceJobId.
Department Not Enabled [403.1035]	HTTP error code 400.1035 Department (sourceDepartmentId) to which this assessment is assigned is not enabled. Assessments in disabled departments cannot be created, modified, or accessed via the API.
Invalid AudienceTypeId [403.1047]	Your request failed. Requested AudienceTypeId is invalid. Error 1047 Optional. Null or 0 or 1. Null and 0 select [Hiring Manager]. 1 selects [Participant].
Invalid ReportTypeId [403.1048]	Your request failed. Requested ReportTypeId is invalid or cannot be used with the current assessment and job. If your value is in the permitted range, then verify that the SourceJobId has job fit enabled. Error 1048 Null and 0 select the default report for the audience, 1 selects [Job Fit Report], 2 selects [Spotlight Report], and 3 selects [Participant Report].
API Request Limit Exceeded [429.1046]	Most API exceptions are due to invalid parameters. Review the notes below each parameter as well as the output and HTTP response code from the error message. If all values are appropriate, the failure is likely authentication-related. Authentication failure types include, but are not limited to,: Too many failed calls Maximum per minute or per day API calls reached API call made via insecure connection Invalid API key API is not enabled for target company API is disabled for all companies (typically during maintenance) Company is inactive or expired Invalid username User is inactive or expired Unknown sourceJobId - check your API job assignments in the primary Berke customer site Invalid assessment complete action <?xml version="1.0" encoding="utf-16"?> <berkeResponse status="[!=ok]" response="[API Method] API method requests exceeded burst limit of 120 occurrences within 60000 milliseconds. Excess requests occurred 3 times from [2024-11-22T09:35:41.0798280Z] to [2024-11-22T09:35:41.6798280Z]." responseCode="429" callDeniedDateTime="2024-11-22T09:35:41.779828Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-11-22T09:35:41.479828Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" /> { "callDeniedDateTime": "2024-11-22T09:35:41.779828Z", "callExpiresOnCompletion": true, "countCallsExceeded": 3, "estimatedMillisecondsToNextAllowedCall": 423, "firstCallDeniedDateTime": "2024-11-22T09:35:41.479828Z", "isDailyLimit": false, "maximumCallsPerTimeFrame": 120, "timeFrameMilliseconds": 60000, "status": "[!=ok]", "response": "[API Method] API method requests exceeded burst limit of 120 occurrences within 60000 milliseconds. Excess requests occurred 3 times from [2024-11-22T09:35:41.0798280Z] to [2024-11-22T09:35:41.6798280Z].", "responseCode": "429" } API requests exceeded the maximum allowed per time-frame or the maximum allowed at any point in time. API throttle limits are set per-company. Please login and return to this area to see your company's specific throttle configuration. Your application can use the following API method response information to determine its course of action when HTTP status code 429 is returned by an API method call: callDeniedDateTime: The date and time that the API method call was denied execution. callExpiresUponCompletion: If this value is true then too many simultaneous calls occurred to a particular group of API methods. If this value is false then too many requests occurred for a particular time frame (daily or short-term). countCallsExceeded: The count of calls that exceeded the maximum number of allowed API calls for the time frame. estimatedMillisecondsToNextAllowedCall: The estimated number of milliseconds, from the callDeniedDateTime, before an API call will be allowed to execute. If callExpiresUponCompletion is true then this value will be zero as the time is dependent on numerous factors. If callExpiresUponCompletion is false then this value indicates the amount of time your application(s) should wait before attempting to make the same API method call. If a daily API call limit has been exceeded the this value indicates the amount of time your application(s) should wait before calling any API method. firstCallDeniedDateTime: The date and time that the first call, of potentially many calls, was denied for the time frame. For example, if an application was denied ten calls within a time frame then firstCallDeniedDateTime indicates date and time that the first of the ten calls was denied. isDailyLimit: If this value is true then the response indicates that the maximum number of API methods calls for the current day has been exceeded. If this value is false then the response indicates that the maximum number of API method calls for a time frame, other than daily, has been exceeded. maximumCallsPerTimeFrame: Indicates the maximum number of times an API method can be called for daily, short-term or simultaneous call limits. timeFrameMilliseconds: Indicates the number of milliseconds in which maximumCallsPerTimeFrame API method calls is allowed.
Other Failure Types [!=200]	Too many failed calls Maximum per minute or per day API calls reached API call made via insecure connection Invalid API key API is not enabled for target company API is disabled for all companies (typically during maintenance) Company is inactive or expired