This recipe demonstrates the staged OV ordering flow with the current TLS API. The technical order starts through the public API, but the provider order is not submitted immediately if organization details are still missing or incomplete. In that case, the API returns action_required=true together with a completion_url.

The important distinction from a normal DV flow is that the certificate id already exists at API level, but the provider-facing order still has to be completed by binding a usable TLS organization. With the current API, that can happen either through POST /tls/certificate/{certificate_id}/complete with a public org_id, or manually in the regfish Console through completion_url.

Prerequisites

• an API key with access to the TLS and DNS endpoints
• a valid CSR for the OV certificate
• a usable TLS organization or enough data to create one
• DNS access for the later DCV step
• optionally, a browser-based user flow for the Console fallback

Step 1: Identify an OV product

Read the TLS product catalog first and select a product that clearly requires organization data.

curl --request GET \
  --url 'https://api.regfish.com/tls/products' \
  --header 'x-api-key: YOUR_API_KEY'

Choose a product with at least:

• type = OV
• validation_level = ov
• organization_required = true

For this example, SecureSite is used as the OV product.

Step 2: Resolve the public TLS organization id

For organization-validated certificates, org_id now expects the public TLS organization id from the regfish TLS API. These ids look like hdl_7K9QW3M2ZT8HJ, not like legacy numeric CA-side ids.

List existing organizations first:

curl --request GET \
  --url 'https://api.regfish.com/tls/organization' \
  --header 'x-api-key: YOUR_API_KEY'

Choose an organization with at least:

• id = hdl_...
• status = ready
• usable_for_ordering = true

If no usable organization exists yet, create one:

curl --request POST \
  --url 'https://api.regfish.com/tls/organization' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "organization": "Example GmbH",
  "first_name": "Ada",
  "last_name": "Admin",
  "address": "Musterstrasse 1",
  "postal_code": "10115",
  "city": "Berlin",
  "country_code": "DE",
  "phone": "+49 30 1234567",
  "email": "admin@example.com"
}
'

Persist the returned public organization id, for example:

• org_id = hdl_7K9QW3M2ZT8HJ

Step 3: Create the OV order through the API

To demonstrate the staged flow intentionally, create the order without org_id. That causes the API to create the local TLS resource first and then ask the client to finish the provider-side order.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "SecureSite",
  "common_name": "www.example.com",
  "dns_names": ["api.example.com"],
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "validity_days": 199
}
'

For a staged OV order, the response should typically contain:

• id
• status = pending
• action_required = true
• pending_reason = organization_required or completion_required
• pending_message
• completion_url
• organization_id = null

A typical application flow looks like this:

const certificate = data.response;

if (certificate.action_required && certificate.completion_url) {
  window.location.assign(certificate.completion_url);
  return;
}

Persist at least the following values before redirecting:

• id
• product
• action_required
• pending_reason
• organization_id
• completion_url

Step 4: Complete the staged order via API with org_id

If you already know a usable public TLS organization id, complete the staged order directly through the API:

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/ABCDEFGHJKM23/complete' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "org_id": "hdl_7K9QW3M2ZT8HJ"
}
'

After a successful completion call, expect at least:

• action_required = false
• organization_id = hdl_7K9QW3M2ZT8HJ
• the same certificate id as before

This is the recommended machine-to-machine path when your integration already knows which usable TLS organization should be bound.

Step 5: Optional fallback through the regfish Console

If your application cannot select the organization itself, open exactly the completion_url returned by the API. For staged orders, this leads to the Console completion route on the same certificate ID.

The user then completes the missing business data there:

• choose an existing usable organization, or
• create a new DigiCert organization, or
• finish the staged order if the Console asks for one more confirmation step

The important point is that this does not create a new certificate id. The same certificate id continues after the Console step.

If the user is not logged in yet, the Console login flow should bring them back to the completion route afterwards.

Step 6: Confirm that the staged state is gone

After the order has been completed through either path, poll the same certificate again through the API.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/ABCDEFGHJKM23' \
  --header 'x-api-key: YOUR_API_KEY'

At this point, expect at least:

• action_required = false
• organization_id = hdl_...
• no further blocking completion_url
• a normal pending order state
• validation details once DCV is ready

From here on, the flow behaves like a normal certificate order on the same certificate id.

Step 7: Apply the DCV record returned after completion

Once the completed order exposes validation.dns_records, apply the DNS record as usual.

curl --request POST \
  --url 'https://api.regfish.com/dns/rr' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "CNAME",
  "name": "_dnsauth.example.com",
  "data": "0123456789abcdef.dcv.digicert.com.",
  "ttl": 300
}
'

Step 8: Poll until issuance and download the certificate

Continue polling the same certificate id until the certificate has been issued and is ready for download.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/ABCDEFGHJKM23' \
  --header 'x-api-key: YOUR_API_KEY'

Watch in particular:

• status
• order_state
• validation
• certificate_pem_available

Once the certificate is ready, download it as usual:

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/ABCDEFGHJKM23/download/pem' \
  --header 'x-api-key: YOUR_API_KEY' \
  --output 'certificate-ABCDEFGHJKM23.pem'

Practical notes for production workflows

• pass org_id only as the public TLS organization id from /tls/organization, for example hdl_7K9QW3M2ZT8HJ
• if you already know a usable organization, you can also send the same org_id directly on POST /tls/certificate to avoid the staged completion step entirely
• use the staged pattern intentionally for OV and later EV-style products where business data may still be missing
• persist completion_url and pending_reason so support and automation can explain why the order is blocked
• treat organization_id = null as "not bound yet", not as a numeric zero value
• do not create a replacement order after Console completion; continue polling the same certificate id
• redirect the user only to the API-provided completion_url, not to a hardcoded Console path
• once the staged state is cleared, handle DCV, polling, and download exactly like any other order

Result

This workflow starts the OV order through the API, binds the same staged certificate to a usable TLS organization via public org_id, and then continues DCV and issuance on the same certificate ID. That keeps the integration aligned with the current TLS API while still leaving completion_url as a manual fallback.