Creating Forms

Create a new Form.


POST https://utilityapi.com/api/v2/forms
# Create a default authorization form
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    'https://utilityapi.com/api/v2/forms'
# Create a form prefilled with a customer_email and utility
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"customer_email": "heather.homeowner@yahoo.com", "utility": "LADWP"}' \
    'https://utilityapi.com/api/v2/forms'
# Create a re-authorization Form for an expired Authorization
curl -X POST -H 'Authorization: Bearer API_TOKEN_HERE' \
    -d '{"authorization_uid": "12345"}' \
    'https://utilityapi.com/api/v2/forms'

The request body must be a valid JSON object. Below are the possible parameters for the object. If a parameter isn't included the default value is used.

Parameter Format Default Description Example
template_uid UID String Newest enabled Template Unique identifier of the Template on which the form is based. This is a fixed uid for most users. "934845-8234"
authorization_uid UID String or null null Unique identifier of the Authorization for which this Form is an update. This is null for new Forms and a string uid for reauthorizations. null
customer_email String or null null Prefill value of the utility customer email field on the authorization form. If null, this field is left blank and will need to be filled in by the utility customer. "heather.homeowner@aol.com"
utility UtilityID or null null The default selection for the utility in the authorization form. If null, the utility customer will need to select their utility from a dropdown. "PG&E"
scope Scope {} Any non-default authorization scope parameters that is being requested. If not set, the default authorization scope is set ({}). {"expires": "until_revoked"}

Returns the created Form object.

// Example result
{
    "uid": "12345",
    "created": "2016-01-01T12:30:24.653422+00:00",
    "updated": "2016-01-01T12:30:24.653422+00:00",
    "template_uid": "123423435",
    "authorization_uid": null,
    "url": "https://utilityapi.com/authorize/example_solar?f=097jiosd-8iy5xci23-14fsasaf",
    ...
}
Code Response Format Description
200 Form Successful request.
400 Error The query parameters included are malformed. Check the error in the response for the type of error:
  • invalid_param
  • invalid_user
  • invalid_template
  • invalid_authorization
  • invalid_customer_email
  • invalid_utility
  • invalid_scope
  • invalid_expires
  • ... - 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.
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).