Test Submitting Forms

Create a test Authorization as if it were submitted using a Form.

POST https://utilityapi.com/api/v2/forms/form_uid/test-submit
# Submit a demo authorization
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"utility": "DEMO", "scenario": "residential"}' \
    'https://utilityapi.com/api/v2/forms/1234/test-submit'
# Submit a commercial demo authorization
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"utility": "PG&E", "scenario": "commercial"}' \
    'https://utilityapi.com/api/v2/forms/1234/test-submit'
# Submit an authorization with an invalid login
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"utility": "SDG&E", "scenario": "badlogin"}' \
    'https://utilityapi.com/api/v2/forms/1234/test-submit'

The request body must be a valid JSON object. Below are the parameters that must be included.

Parameter Format Description Example
utility UtilityID

The utility for which to submit a test authorization.

"DEMO"
scenario Test scenario The type of test credentials to submit. "residential"

All utilities have some basic demonstration scenarios, which are listed below. Some utilities also have additional test scenarios to help you handle more scenarios gracefully.

Scenario to use in
/test-submit
Username to use in
Authorization Forms
Description
residential UAPI_TEST_residential Will simulate finding 1 residential meter.
commercial UAPI_TEST_commercial Will simulate finding 4 commercials meters.
badlogin UAPI_TEST_badlogin Will simulate an error for an authorization that has invalid login credentials.
badlogin_after UAPI_TEST_badlogin_after Will return a meter, then simulate the badlogin error when trying to collect data for that meter.
websitedown UAPI_TEST_websitedown Will simulate an error for the utility website being down.
websitedown_after UAPI_TEST_websitedown_after Will return a meter, then simulate the websitedown error when trying to collect data for that meter.
utilityerror UAPI_TEST_utilityerror Will simulate an error encountered on the utility.
utilityerror_after UAPI_TEST_utilityerror_after Will return a meter, then simulate an error encountered on the utility when trying to collect data.
locked UAPI_TEST_locked Will simulate a login being locked out.
locked_after UAPI_TEST_locked_after Will return a meter, then simulate a login being locked out when trying to collect data.
access_code_needed UAPI_TEST_access_code_needed Will simulate a login needing multi-factor authentication.
access_code_needed_after UAPI_TEST_access_code_needed_after Will return a meter, then simulate a login needing multi-factor authentication when trying to collect data.
randomerror UAPI_TEST_randomerror Will simulate an unexpected error.
randomerror_after UAPI_TEST_randomerror_after Will return a meter, then simulate an unexpected error when trying to collect data.
empty UAPI_TEST_empty Will simulate an account without any meters.
revoked UAPI_TEST_revoked Will return a meter, then simulate that meter being revoked when trying to collect data for that meter.
expired UAPI_TEST_expired Will return a meter, then simulate that meter being expired when trying to collect data for that meter.
nobills UAPI_TEST_nobills Will return a meter, then simulate there being no bills available for that meter.
nointervals UAPI_TEST_nointervals Will return a meter, then simulate there being no intervals available for that meter.
partialmeters UAPI_TEST_partialmeters Will simulate finding only part of the full meter list (because the utility errored in loading the full meter list).
partialbills UAPI_TEST_partialbills Will return a meter, then simulate only some bills being available and others erroring.
partialintervals UAPI_TEST_partialintervals Will return a meter, then simulate only some intervals being available and others erroring.

Certain utilities have scenarios to demonstrate behavior unique to that utility.

Utility Scenario to use in
/test-submit
Username to use in
Authorization Forms
Description
PG&E pge_cca_service UAPI_TEST_pge_cca_service Will simulate a PG&E authorization with a CCA service and its parent service with bills containing suppliers blocks with the CCA data.

Returns a created Referral object. You can use the referral code to look up the authorization in GET /authorizations.

// Example response
{
    "referral": "12345-56789"
}

This is the object that contains a referral code that you can use to look up the created Authorizations with this test-submit. We return a referral code for the test-submit endpoint because that is the code you would get in the query parameters of your url redirect if someone were to submit an authorization through this authorization form.

Parameter Format Description Example
referral String Referral code that can be used to look up the Authorization via GET /authorizations?referrals=... "12345-56789"
// Example Referral object
{
    "referral": "12345-56789"
}
Code Response Format Description
200 Referral Successful request.
400 Error The POST parameters are malformed. Check the error in the response for the type of error:
  • invalid_param
  • ... - We may add more error types in the future, so be able to handle unknown types.
401 Error Invalid or missing access_token. See our docs on Authentication for how to properly use your access_token.
404 Error This Form doesn't exist or you don't have permissions to see it.
429 N/A The request was rate limited. Check the Retry-After response header for how long to wait until retrying the request. Do not expect any specific response format for this error (could be html, json, or nothing).
500 N/A Internal server error. Do not expect any specific response format for this error (could be html, json, or nothing). This error is logged and will be fixed by our engineers.
503 N/A Site is currently down for maintenance. Do not expect any specific response format for this error (could be html, json, or nothing).
504 N/A We tried to build this request but timed out. Please try again later. Do not expect any specific response format for this error (could be html, json, or nothing).