Common API Calls
As a SaaS provider, you may want to configure and manage Cloudflare for SaaS via the API rather than the Cloudflare dashboard ↗. Below are relevant API calls for creating, editing, and deleting custom hostnames, as well as monitoring, updating, and deleting fallback origins. Further details can be found in the Cloudflare API documentation.
| Endpoint | Notes |
|---|---|
| List custom hostnames | Use the page parameter to pull additional pages. Add a hostname parameter to search for specific hostnames. |
| Create custom hostname | In the validation_records object of the response, use the txt_name and txt_record listed to validate the custom hostname. |
| Custom hostname details | Use this endpoint to check hostname activation and certificate status. |
| Edit custom hostname | When sent with an ssl object that matches the existing value, indicates that hostname should restart domain control validation (DCV). |
| Delete custom hostname | Also deletes any associated SSL/TLS certificates. |
To confirm that a custom hostname is fully configured, check both status fields in the Custom hostname details endpoint response:
| API field | What it means | Ready value |
|---|---|---|
result.status | Hostname activation status. This field shows whether Cloudflare has validated and activated the custom hostname. | active |
result.ssl.status | Certificate status. This field shows whether the hostname's SSL/TLS certificate has completed issuance and deployment. | active |
Treat the custom hostname as ready for production HTTPS when result.status is active, result.ssl.status is active, and the customer's DNS points to your CNAME target or apex proxying target.
If result.status is active but result.ssl.status is not active, the hostname is active but its certificate has not completed issuance and deployment. A successful TLS handshake alone does not mean the custom hostname certificate has finished provisioning because Cloudflare may present another matching certificate for that hostname. For more information, refer to Certificate and hostname priority.
When you use the Create custom hostname endpoint, choose one ssl.method value: http, txt, or email. For non-wildcard custom hostnames, Cloudflare always attempts HTTP certificate validation after the hostname points to your SaaS target, even if you selected TXT validation.
Our API includes the following endpoints related to the fallback origin of a custom hostname: