Get Service Agreement
get
/spl/rest/apis/customer/v-model/serviceAgreements/{serviceAgreementId}
Request
Path Parameters
There's no request body for this operation.
Back to TopResponse
Supported Media Types
- application/xml
- application/json
200 Response
Success response
Root Schema : C1-ServiceAg
Type:
Show Source
object
-
_self: string
_self
-
account: object
account
-
allowEstimates: boolean
Turn on Allow Estimates if it's OK for the billing process to estimate this service agreement's consumption if a real meter read is missing at billing time
-
billMessages: object
billMessages
-
businessActivityDescription: string
Maximum Length:
250
Enter a Business Activity associated with the customer. This can be used to further define what types of activities are served by this contract.Example:business
-
characteristics: object
characteristics
-
consumerContractProducts: object
consumerContractProducts
-
contractOptions: object
contractOptions
-
contractQuantities: object
contractQuantities
-
contractTerms: object
contractTerms
-
currency: object
currency
Currency Code
-
customerRead: string
Allowed Values:
[ "N ", "Y " ]
Use Customer Read to define if the customer reads his or her own meter. Valid values are: Yes, No. * `N ` - No, * `Y ` - YesExample:Y
-
depositInterestCalculated: string
(date)
Deposit Interest Calculated contains the last date the system applied interest. This field is only visible if the SA type has a special role of Cash Deposit.Example:
2018-02-25
-
endDate: string
(date)
The End Date defines when the financial relationship terminates.Example:
2018-02-25
-
expireDate: string
(date)
Expiration Date contains the date at which the service agreement is set to expire.
-
ibSACutoffTime: string
If the SA Type has a special role of Interval, you must enter the Cutoff Time. The Cutoff Time is entered in "legal time". This value defaults from either the start option or the installation record.
-
isActive: boolean
IsActive flag to show active SAs for accountExample:
false
-
maxBillThreshold: number
Use Maximum Bill Threshold if you want the system to generate a bill error when a bill segment is produced in batch that exceeds a given value.Example:
2000
-
nonBillAutoPay: string
Allowed Values:
[ "EXCL", "INCL" ]
The Scheduled Payment Autopay flag determines if the non-billed budget scheduled payments are excluded from automatic payment or included by automatic payment. If the account is not set up for automatic payment for the period that covers the non-billed budget, this flag cannot be set. This field is only visible if the SA has a special role of Non-billed Budget * `EXCL` - Excluded from Auto Pay, * `INCL` - Included in Auto PayExample:INCL
-
numberOfPaymentPeriods: number
Minimum Value:
0
Maximum Value:999
Number of Payment Periods only appears for loan SA types. It displays the number of periods specified when the loan was first activated.Example:0
-
oldAccountId: string
Maximum Length:
36
Old Account ID refers to account id for service agreements that were converted from your legacy CIS system. The payment upload process uses this field to locate the accounts for payments that reference a legacy account numberExample:123456789
-
order: object
order
-
premise: object
premise
-
rateScheduleHistory: object
rateScheduleHistory
-
recommendationRule: string
Maximum Length:
8
The NBB Recommendation Rule displays the description of the non-billed budget recommendation rule used for this SA. This field is only visible if the SA has a special role of Non-billed Budget. -
recurringChargeHistory: object
recurringChargeHistory
-
renewalDate: string
(date)
Renewal Date contains the date at which the service agreement is to be renewed. Renewal date is disabled if renewal is not allowed on the SA type.
-
reviewDate: string
(date)
CIAC Review Date displays the last date that the Contributions In Aid of Construction (CIAC) review process ran for this service agreement. This field is only visible if the SA type indicates this is a CIAC service agreement.
-
saStatusDescription: string
Maximum Length:
60
Description for SA StatusExample:Canceled
-
serviceAgreementId: string
Maximum Length:
10
The Service Agreement ID is a system assigned random number that stays with a service agreement for life. -
serviceAgreementRelationship: object
serviceAgreementRelationship
-
serviceAgreementType: object
serviceAgreementType
-
servicePoints: object
servicePoints
-
serviceType: object
serviceType
Service Type defines the type of service associated with the SA type.
-
sicCode: object
sicCode
Select the SIC Code associated with the customer. This is typically only used for commercial and industrial customers.
-
specialRole: string
Allowed Values:
[ "BC ", "BD ", "CD ", "IN ", "LO ", "NB ", "PA ", "WO " ]
Special Role: * `BC ` - Billable Charge, * `BD ` - Bill Determinants Required, * `CD ` - Cash Deposit, * `IN ` - Interval, * `LO ` - Loan, * `NB ` - Non-billed Budget, * `PA ` - Payment Arrangement, * `WO ` - Write Off -
specialUsage: string
Allowed Values:
[ "PROP" ]
The Special Usage Flag shows if the SA is a proposal SA . You cannot create a quote unless its account has at least one proposal service agreement (SA). A proposal SA contains the pricing terms, legal terms, and template consumption used to generate the simulated bill segments that appear on a quote. It might be helpful to view a proposal SA as special type of service agreement that is ignored when a bill is produced for an account. * `PROP` - Proposal SAExample:PROP
-
startDate: string
(date)
The Start Date defines when the financial relationship begins.
-
startOption: string
Maximum Length:
12
Start options save users time and prevent data entry errors because they default many values on a service agreement (e.g., the rate schedule, recurring charge amount, contract riders, contract terms, characteristics, terms and conditions, etc. can all be defaulted onto a service agreement from a start option). -
startReason: string
Allowed Values:
[ "C ", "S " ]
Use Start Reason to define who requested to start the SA on the Start Stop page. * `C ` - Customer Request, * `S ` - System GeneratedExample:C
-
startRequestedBy: string
Maximum Length:
50
Start Requested By displays the information entered in the Requested By field on the Start Stop page when this SA was started (e.g., Customer, Jane Smith ). -
status: string
Allowed Values:
[ "05 ", "10 ", "20 ", "30 ", "40 ", "50 ", "60 ", "70 " ]
SA Status defines the state of the service agreement. * `05 ` - Incomplete, * `10 ` - Pending Start, * `20 ` - Active, * `30 ` - Pending Stop, * `40 ` - Stopped, * `50 ` - Reactivated, * `60 ` - Closed, * `70 ` - CanceledExample:20
-
stopReason: string
Allowed Values:
[ "C ", "S " ]
Use Stop Reason to define who requested to stop the SA on the Start Stop page. * `C ` - Customer Request, * `S ` - System GeneratedExample:C
-
stopRequestedBy: string
Maximum Length:
50
Stop Requested By displays the information entered in the Requested By field on the Start Stop page when this SA was stopped (e.g., Customer, Jane Smith ). -
termsAndConditions: object
termsAndConditions
-
totalAmountToBill: number
If the service agreement requires a total amount to bill, the amount is displayed. This field is typically only used on loan or cash deposit service agreements.
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : account
Type:
Show Source
object
-
_link: string
_link
-
accountId: string
Maximum Length:
10
Account ID is financially responsible for the service agreement. If you change a service agreement's Account ID, you are effectively transferring this service agreement (and its debt) to the new account.Example:1589809012
Nested Schema : currency
Type:
object
Currency Code
Show Source
-
_link: string
_link
-
currency: string
Maximum Length:
3
Currency CodeExample:USD
Nested Schema : order
Type:
Show Source
object
-
_link: string
_link
-
orderId: string
Maximum Length:
12
Order ID is the system-assigned unique identifier of the order.
Nested Schema : premise
Type:
Show Source
object
-
_link: string
_link
-
premiseId: string
Maximum Length:
10
If the service agreement's rate uses premise-based characteristics for taxation and other purposes, Characteristic Premise ID defines the premise that supplies these characteristics. This field also defines the premise under which the service agreement's bill segments are classified and is used to identify where the service agreement's service is located.Example:8614900960
Nested Schema : serviceAgreementRelationship
Type:
Show Source
object
-
_link: string
_link
-
saRelationshipId: string
Maximum Length:
10
SA Relationship ID
Nested Schema : serviceAgreementType
Type:
Show Source
object
-
_link: string
_link
-
division: string
Maximum Length:
5
The CIS division on SA is actually part of the SA's SA type. Because SA type controls many business rules, all business rules that are on the SA type can be thought of as being defined for a given jurisdiction and SA type combination.Example:Ohio
-
divisionDescription: string
Maximum Length:
1
The CIS division on SA is actually part of the SA's SA type. Because SA type controls many business rules, all business rules that are on the SA type can be thought of as being defined for a given jurisdiction and SA type combination.Example:Ohio
-
saType: string
Maximum Length:
8
The CIS division on SA is actually part of the SA's SA type. Because SA type controls many business rules, all business rules that are on the SA type can be thought of as being defined for a given jurisdiction and SA type combination.Example:Ohio
-
serviceAgreementTypeDescription: string
Maximum Length:
30
The CIS division on SA is actually part of the SA's SA type. Because SA type controls many business rules, all business rules that are on the SA type can be thought of as being defined for a given jurisdiction and SA type combination.Example:Ohio
Nested Schema : serviceType
Type:
object
Service Type defines the type of service associated with the SA type.
Show Source
-
_link: string
_link
-
serviceType: string
Maximum Length:
80
Service Type defines the type of service associated with the SA type.Example:E
Nested Schema : sicCode
Type:
object
Select the SIC Code associated with the customer. This is typically only used for commercial and industrial customers.
Show Source
-
_link: string
_link
-
sicCode: string
Maximum Length:
8
Select the SIC Code associated with the customer. This is typically only used for commercial and industrial customers.Example:4800 (Transportation)
Nested Schema : items
Type:
Show Source
object
-
billMessage: object
billMessage
-
billMessageType: string
Allowed Values:
[ "P ", "T " ]
For Bill Message Type, use Temporary to indicate the message should only be linked to the next bill produced for the account. Use Permanent if the message should appear on every bill. Note, a value of Temporary defaults. * `P ` - Permanent, * `T ` - TemporaryExample:T
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : billMessage
Type:
Show Source
object
-
_link: string
_link
-
billMessage: string
Maximum Length:
4
Bill Message
Nested Schema : items
Type:
Show Source
object
-
characteristicType: object
characteristicType
-
characteristicValue: object
characteristicValue
-
effectiveDate: string
(date)
Effective Date Indicate the effective date of the characteristic type and value. The service point's install date defaults.Example:
2018-02-25
-
typeOfCharacteristicValue: string
Allowed Values:
[ "ADV ", "DFV ", "FKV ", "FLV " ]
Type of Char Value: * `ADV ` - Adhoc Value, * `DFV ` - Predefined Value, * `FKV ` - Foreign Key Value, * `FLV ` - File Location Value -
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : characteristicType
Type:
Show Source
object
-
_link: string
_link
-
characteristicType: string
Maximum Length:
8
Characteristic Type
Nested Schema : characteristicValue
Type:
Show Source
object
-
_link: string
(_link)
-
value: string
Maximum Length:
254
Ad hoc Characteristics Value do not have their valid values defined in a discreet list because the possible values are infinite. Good examples of such a characteristic type would be ones used to define a user's birth date or their mother's maiden name.Example:77
-
value2: string
Maximum Length:
50
Foreign Key Value 2 -
value3: string
Maximum Length:
50
Foreign Key Value 3 -
value4: string
Maximum Length:
50
Foreign Key Value 4 -
value5: string
Maximum Length:
50
Foreign Key Value 5
Nested Schema : items
Type:
Show Source
object
-
consumerContractProduct: object
consumerContractProduct
-
consumerContractRule: object
consumerContractRule
-
consumerProductComponent: object
consumerProductComponent
-
effectiveDate: string
(date)
Effective DateExample:
2018-02-25
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : consumerContractProduct
Type:
Show Source
object
-
_link: string
_link
-
consumerContractProductId: string
Maximum Length:
14
Consumer Contract Product
Nested Schema : consumerContractRule
Type:
Show Source
object
-
_link: string
_link
-
consumerContractRule: string
Maximum Length:
30
Consumer Contract Rule
Nested Schema : consumerProductComponent
Type:
Show Source
object
-
_link: string
_link
-
consumerProductComponent: string
Maximum Length:
30
Consumer Product Component
Nested Schema : items
Type:
Show Source
object
-
contractOption: object
contractOption
-
effectiveDateTime: string
(date-time)
Effective Date/Time This is the date and time that the contract option is in effect for the service agreement.Example:
2018-02-25
-
expirationDateTime: string
(date-time)
Expiration Date/Time This is the date and time that the contract option is no longer in effect for the service agreement.Example:
2006-07-01T00:00:00-04:00
-
saContractOptionId: string
Maximum Length:
12
The SA Contract Option ID is the unique identifier of the SA / contract option record.Example:301631110794
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : contractOption
Type:
Show Source
object
-
_link: string
_link
-
contractOptionId: string
Maximum Length:
12
Contract Option ID
Nested Schema : items
Type:
Show Source
object
-
contractQuantity: number
Minimum Value:
-1.0E11
Maximum Value:1.0E11
The contract quantity.Example:10.000000
-
contractQuantityType: object
contractQuantityType
-
effectiveDate: string
(date)
Effective Date Indicate the effective date of the characteristic type and value. The service point's install date defaults.Example:
2018-02-25
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : contractQuantityType
Type:
Show Source
object
-
_link: string
_link
-
contractQuantityType: string
Maximum Length:
8
Contract Quantity Type
Nested Schema : items
Type:
Show Source
object
-
billFactor: object
billFactor
-
contractTermType: string
Allowed Values:
[ "R ", "T ", "V " ]
Billing uses Contract Term information when it calculates a bill segment for the service agreement. The Contract Rider grid contains the contract riders that are in effect for the service agreement. The Contract Values grid contains the contract values that are in effect for the service agreement. The Tax Exemptions section contains the taxes from which the service agreement is all or partially exempt. * `R ` - Contract Rider, * `T ` - Tax Exemption, * `V ` - Contract ValueExample:R
-
endDate: string
(date)
The End Date defines when the financial relationship terminates.Example:
2018-02-25
-
percentExempt: number
Minimum Value:
-999.9999
Maximum Value:999.9999
Use Percent Exempt to define the customer tax exemption percent (e.g., 90 means the customer is 90% exempt and will only pay 10% of the normal tax rate).Example:0.0000
-
startDate: string
(date)
The Start Date defines when the financial relationship begins.
-
taxCertification: string
Maximum Length:
35
Use Tax Certification if the customer has a tax exemption certificate. -
taxExemptType: object
taxExemptType
-
touGroup: string
Maximum Length:
30
Indicate the TOU Group that corresponds with the TOU group on the service agreement's TOU Map. Once entered, the collection of TOU codes linked to this TOU group will display. -
value: number
Minimum Value:
-1.0E11
Maximum Value:1.0E11
For each Time of Use code, enter the appropriate Value. -
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : billFactor
Type:
Show Source
object
-
_link: string
_link
-
billFactor: string
Maximum Length:
8
Bill Factor
Nested Schema : taxExemptType
Type:
Show Source
object
-
_link: string
_link
-
taxExemptType: string
Maximum Length:
8
Tax Exempt Type
Nested Schema : items
Type:
Show Source
object
-
effectiveDate: string
(date)
Effective Date Indicate the effective date of the characteristic type and value. The service point's install date defaults.Example:
2018-02-25
-
rateSchedule: object
rateSchedule
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : rateSchedule
Type:
Show Source
object
-
_link: string
_link
-
rateSchedule: string
Maximum Length:
8
Rate Schedule
Nested Schema : items
Type:
Show Source
object
-
currency: object
currency
-
effectiveDate: string
(date)
Effective Date Indicate the effective date of the characteristic type and value. The service point's install date defaults.Example:
2018-02-25
-
recurringChargeAmount: number
The Recurring Charge contains effective-dated information that defines the recurring charge amount used to calculate the service agreement's bill segments.Example:
5000
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : currency
Type:
Show Source
object
-
_link: string
_link
-
currency: string
Maximum Length:
3
Currency Code
Nested Schema : items
Type:
Show Source
object
-
howToUseRead: string
Allowed Values:
[ "+ ", "- ", "C ", "S ", "X " ]
How to Use (SP) Indicates how billing uses the consumption associated with the service point. This field is gray for item-type service points. * `+ ` - Add, * `- ` - Subtract, * `C ` - Check, * `S ` - Service Quantity, * `X ` - Calculation/AuditExample:S
-
saSPId: string
Maximum Length:
10
System assigned record key for the SA/SP relationship -
servicePoint: object
servicePoint
-
startDateTime: string
(date-time)
Start Date/Time The date and time the service point's consumption starts being billed under the service agreement.
-
startMeterRead: object
startMeterRead
-
stopDateTime: string
(date-time)
The date and time the service point's consumption stops being billed under the service agreement.
-
stopMeterRead: object
stopMeterRead
-
usePercent: number
Minimum Value:
-999.99
Maximum Value:999.99
Use Percent Indicates the percentage of this service point's consumption that is billed under the service agreement. This field is not applicable for item-type service points.Example:100
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : servicePoint
Type:
Show Source
object
-
_link: string
_link
-
servicePointId: string
Maximum Length:
10
Service Point ID
Nested Schema : startMeterRead
Type:
Show Source
object
-
_link: string
_link
-
startMeterReadId: string
Maximum Length:
12
Meter Read ID
Nested Schema : stopMeterRead
Type:
Show Source
object
-
_link: string
_link
-
stopMeterReadId: string
Maximum Length:
12
Meter Read ID
Nested Schema : items
Type:
Show Source
object
-
endDate: string
(date)
The End Date defines when the financial relationship terminates.Example:
2018-02-25
-
startDate: string
(date)
The Start Date defines when the financial relationship begins.
-
termsAndCondition: object
termsAndCondition
-
version: number
Minimum Value:
-99999
Maximum Value:99999
VersionExample:2
Nested Schema : termsAndCondition
Type:
Show Source
object
-
_link: string
_link
-
termsAndCondition: string
Maximum Length:
12
Terms and Conditions
400 Response
Bad Request
Root Schema : problemDetailDocument
Type:
Show Source
object
-
detail: string
Maximum Length:
60
The long message description from the Oracle Utilities Application Framework in CDATA format. -
httpStatus: number
Minimum Value:
0
Maximum Value:9999
The HTTP Status code for the error. -
problemInstance: string
Maximum Length:
60
Fully qualified URL consisting of the Base URI Timestamp of error in ISO format, the User used for the transaction, the Message Category within Oracle Utilities Application Framework, the Message Number within Oracle Utilities Application Framework, the Request URL and the HTTP method used for the transaction. -
problemType: string
Maximum Length:
60
URL of the format "A/message/X/Y" where A is the base URI, X is the Message Category and Y is the Message Number within Oracle Utilities Application Framework. -
serverMessage: object
serverMessage
-
stackTrace: string
Maximum Length:
60
The stack trace shows where the error occurs during the execution of a program. -
title: string
Maximum Length:
60
Fully qualified error message from Oracle Utilities Application Framework in CDATA format.
Nested Schema : serverMessage
Type:
Show Source
object
-
callSequence: string
Maximum Length:
60
Delimited sequence of programs called. -
longDescription: string
Maximum Length:
60
The long message description from the Oracle Utilities Application Framework in CDATA format. -
messageCategory: number
Minimum Value:
0
Maximum Value:0
Message Category within Oracle Utilities Application Framework. -
messageNbr: number
Minimum Value:
-99999
Maximum Value:99999
Message Number within Oracle Utilities Application Framework. -
messageText: string
Maximum Length:
60
Fully qualified error message from Oracle Utilities Application Framework in CDATA format. -
programName: string
Maximum Length:
60
Name of the program that encountered the error.
500 Response
Internal Server Error
Root Schema : problemDetailDocument
Type:
Show Source
object
-
detail: string
Maximum Length:
60
The long message description from the Oracle Utilities Application Framework in CDATA format. -
httpStatus: number
Minimum Value:
0
Maximum Value:9999
The HTTP Status code for the error. -
problemInstance: string
Maximum Length:
60
Fully qualified URL consisting of the Base URI Timestamp of error in ISO format, the User used for the transaction, the Message Category within Oracle Utilities Application Framework, the Message Number within Oracle Utilities Application Framework, the Request URL and the HTTP method used for the transaction. -
problemType: string
Maximum Length:
60
URL of the format "A/message/X/Y" where A is the base URI, X is the Message Category and Y is the Message Number within Oracle Utilities Application Framework. -
serverMessage: object
serverMessage
-
stackTrace: string
Maximum Length:
60
The stack trace shows where the error occurs during the execution of a program. -
title: string
Maximum Length:
60
Fully qualified error message from Oracle Utilities Application Framework in CDATA format.
Nested Schema : serverMessage
Type:
Show Source
object
-
callSequence: string
Maximum Length:
60
Delimited sequence of programs called. -
longDescription: string
Maximum Length:
60
The long message description from the Oracle Utilities Application Framework in CDATA format. -
messageCategory: number
Minimum Value:
0
Maximum Value:0
Message Category within Oracle Utilities Application Framework. -
messageNbr: number
Minimum Value:
-99999
Maximum Value:99999
Message Number within Oracle Utilities Application Framework. -
messageText: string
Maximum Length:
60
Fully qualified error message from Oracle Utilities Application Framework in CDATA format. -
programName: string
Maximum Length:
60
Name of the program that encountered the error.