Creating Forms

Create a new Form.

HTTP Request

POST https://utilityapi.com/api/v2/forms

Examples

# 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'

POST Body

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.

NOTE: All parameters are optional. You only need to include a POST body if you want non-default values in your Form.

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"}`

Response

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",
    ...
}

HTTP Response Codes

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).