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).
sourceDepartmentId
Required, 1-50 characters. The ID of the department for which to set billing information.
Use the
GetDepartmentTree method to retrieve your SourceDepartmentId values if you
do not know them. You can also find your SourceDepartmentId values in the Berke site. (Berke login required)
isBillingEnabled
Required, true or false. If true, then utcBillingStart and billingPlanId must be set.
utcBillingStart
Null or decimal-numeric. Optional except when isBillingEnabled is true. Time will be set to 00:00:00 for the day we receive.
Must be formatted in Unix time offset to UTC. Visit EpochConverter.com
for a demonstration and code samples for converting to/from UTC Unix time.
Current Time: 10/7/2024 11:47:37 PM Eastern Standard Time
Current Time UTC: 10/8/2024 3:47:37 AM UTC
Current Time Unix UTC: 1728359257.08998
utcBillingThrough
Optional. Null or decimal-numeric. Time will be set to 23:59:59 for the day we receive. If not set and utcBillingStart has already occurred, then billing will be enabled.
Must be formatted in Unix time offset to UTC. Visit
EpochConverter.com
for a demonstration and code samples for converting to/from UTC Unix time.
billingPlanId
Required, integer, valid settings include:
1 = not set - note: this value cannot be selected when isBillingEnabled is true
2 = subscription
billingPeriodAmount
Optional, decimal. If supplied, must be 0.0 or greater. If null, value will default to 0.0. All currency is in USD.
billingNotes
Optional, null or 1-500 characters. Do not, under any circumstances, include any card data or other sensitive
information in this field.
billingContact
Optional, recommended.
billingContactEmail
Optional, recommended. Must be a valid email address.
billingContactPhone
Optional, recommended.
reasonForChange
Optional, but highly recommended, null or 1-500 characters. Accountants appreciate good documentation when a billing record changes.
formatOutput
xml
json
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">
<departmentBilling wasChanged="true" changeSummary="[Example change summary... Billing changes recorded: 1: Billing Period Amount changed from [0.00] to [500.00]" reasonForChange="[Example reason... Upgraded from Basic Plan]" billingStatus="Enabled" billingWarning="BillingEnabledButOrganizationDisabled" billingSummary="Summarizes status, plans, etc." billingRecordId="35412" sourceDepartmentId="[sourceDepartmentId]" isBillingEnabled="true" utcBillingStart="1728359257.089982" utcBillingThrough="1759895257.089982" billingPlan="Subscription" billingPlanId="2" billingPeriodAmount="500.0" billingNotes="[Example notes... $500 per month, unlimited]" billingContact="Bilbo Baggins" billingContactEmail="Bilbo@BagEnd.co.uk" billingContactPhone="555-555-5555" />
</berkeResponse>
{
"departmentBilling": {
"wasChanged": true,
"changeSummary": "[Example change summary... Billing changes recorded: 1: Billing Period Amount changed from [0.00] to [500.00]",
"reasonForChange": "[Example reason... Upgraded from Basic Plan]",
"billingStatus": "Enabled",
"billingWarning": "BillingEnabledButOrganizationDisabled",
"billingSummary": "Summarizes status, plans, etc.",
"billingRecordId": 35412,
"sourceDepartmentId": "[sourceDepartmentId]",
"isBillingEnabled": true,
"utcBillingStart": 1728359257.089982,
"utcBillingThrough": 1759895257.089982,
"billingPlan": "Subscription",
"billingPlanId": 2,
"billingPeriodAmount": 500.0,
"billingNotes": "[Example notes... $500 per month, unlimited]",
"billingContact": "Bilbo Baggins",
"billingContactEmail": "Bilbo@BagEnd.co.uk",
"billingContactPhone": "555-555-5555"
},
"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]"
}
Failure [!=200]
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
Department Not Found [403.1034] )
sourceDepartmentId was not found.
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-10-08T03:47:36.3899820Z] to [2024-10-08T03:47:36.9899820Z]." responseCode="429" callDeniedDateTime="2024-10-08T03:47:37.089982Z" callExpiresOnCompletion="true" countCallsExceeded="3" estimatedMillisecondsToNextAllowedCall="423" firstCallDeniedDateTime="2024-10-08T03:47:36.789982Z" isDailyLimit="false" maximumCallsPerTimeFrame="120" timeFrameMilliseconds="60000" />
{
"callDeniedDateTime": "2024-10-08T03:47:37.089982Z",
"callExpiresOnCompletion": true,
"countCallsExceeded": 3,
"estimatedMillisecondsToNextAllowedCall": 423,
"firstCallDeniedDateTime": "2024-10-08T03:47:36.789982Z",
"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-10-08T03:47:36.3899820Z] to [2024-10-08T03:47:36.9899820Z].",
"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.